diff options
| -rw-r--r-- | .build.yml | 23 | ||||
| -rw-r--r-- | .gitignore | 16 | ||||
| -rw-r--r-- | Makefile | 36 | ||||
| -rw-r--r-- | assets/manual/acceleration-distance.ps | 64 | ||||
| -rw-r--r-- | assets/manual/dev-advtrains.tex | 79 | ||||
| -rw-r--r-- | assets/manual/filter_man_md2tex.lua | 28 | ||||
| -rw-r--r-- | assets/manual/man/man3advtrains/rwt_add.3advtrains.md | 20 | ||||
| -rw-r--r-- | assets/manual/man/man3advtrains/rwt_copy.3advtrains.md | 28 | ||||
| -rw-r--r-- | assets/manual/man/man3advtrains/rwt_last_rpt.3advtrains.md | 19 | ||||
| -rw-r--r-- | assets/manual/man/man3advtrains/rwt_now.3advtrains.md | 7 | ||||
| -rw-r--r-- | assets/manual/man/man7advtrains/rwt.7advtrains.md | 24 | ||||
| -rw-r--r-- | assets/manual/tex/a4manual.tex (renamed from assets/manual/a4manual.tex) | 0 | ||||
| -rw-r--r-- | assets/manual/tex/a5manual.tex (renamed from assets/manual/a5manual.tex) | 0 | ||||
| -rw-r--r-- | assets/manual/tex/contributing.tex (renamed from assets/manual/contributing.tex) | 0 | ||||
| -rw-r--r-- | assets/manual/tex/dev-advtrains.tex | 36 | ||||
| -rw-r--r-- | assets/manual/tex/interlocking.tex (renamed from assets/manual/interlocking.tex) | 0 | ||||
| -rw-r--r-- | assets/manual/tex/introduction.tex (renamed from assets/manual/introduction.tex) | 2 | ||||
| -rw-r--r-- | assets/manual/tex/luaatc.tex (renamed from assets/manual/luaatc.tex) | 2 | ||||
| -rw-r--r-- | assets/manual/tex/main.tex (renamed from assets/manual/main.tex) | 1 | ||||
| -rw-r--r-- | assets/manual/tex/manpages.tex | 7 | ||||
| -rw-r--r-- | assets/manual/tex/nodedef.tex (renamed from assets/manual/nodedef.tex) | 0 | ||||
| -rw-r--r-- | assets/manual/tex/physics.tex (renamed from assets/manual/physics.tex) | 0 | ||||
| -rw-r--r-- | assets/manual/tex/preamble.tex (renamed from assets/manual/preamble.tex) | 3 | ||||
| l--------- | assets/manual/tex/screenshot.png | 1 | ||||
| -rw-r--r-- | assets/manual/tex/signals.tex (renamed from assets/manual/signals.tex) | 0 | ||||
| -rw-r--r-- | assets/manual/tex/tables.tex (renamed from assets/manual/tables.tex) | 0 | ||||
| -rw-r--r-- | assets/manual/tex/title.tex (renamed from assets/manual/title.tex) | 2 | ||||
| -rw-r--r-- | assets/manual/tex/tracks.tex (renamed from assets/manual/tracks.tex) | 0 | ||||
| -rw-r--r-- | assets/manual/tex/train-controls.tex (renamed from assets/manual/train-controls.tex) | 0 |
29 files changed, 228 insertions, 170 deletions
@@ -6,8 +6,7 @@ packages: - unzip - wget - lua-busted -- dvisvgm -- ghostscript +- pandoc - texlive-extra-utils - texlive-latex-base - texlive-latex-extra @@ -18,10 +17,9 @@ packages: sources : - https://git.sr.ht/~gpcf/advtrains artifacts: -- .minetest/mods/advtrains/assets/manual/acceleration-distance.pdf -- .minetest/mods/advtrains/assets/manual/a4manual.pdf -- .minetest/mods/advtrains/assets/manual/a5manual.pdf -- .minetest/mods/advtrains/assets/manuals.tar.xz +- .minetest/mods/advtrains/assets/manual/tex/a4manual.pdf +- .minetest/mods/advtrains/assets/manual/tex/a5manual.pdf +- .minetest/mods/advtrains/assets/manual/man.tar.xz tasks: @@ -61,15 +59,4 @@ tasks: echo "bind_address = 127.0.0.1" > minetest.conf ~/bin/minetestserver --port 31111 --gameid minetest_game --config ~/minetest.conf --world ~/.minetest/worlds/advtrains_testworld - generate_documentation: | - cd ~/.minetest/mods/advtrains/assets/manual - for i in a4manual.tex a5manual.tex; do - for run in {1..2}; do - pdflatex -interaction=nonstopmode -halt-on-error -output-format=pdf $i - done - done - make4ht -f 'html5+tidy' a4manual.tex - for i in acceleration-distance.ps; do - ps2pdf $i - done - cd .. - find ./manual -name '*.pdf' -o -name '*.svg' -o -name '*.html' -o -name '*.css' | tar -cJf manuals.tar.xz -T - + make -C ~/.minetest/mods/advtrains/ doc @@ -1,9 +1,13 @@ ## Eclipse project files & directories .project .settings -assets/screenshot.png -assets/manual/* -!assets/manual/*.tex -!assets/manual/*.ps -!assets/manual/*.lua -assets/manual/_region_*
\ No newline at end of file + +assets/manual/tex/* +!assets/manual/tex/*.tex +!assets/manual/tex/screenshot.png +assets/manual/tex/man.tex +assets/manual/tex/_region_* + +assets/manual/man/**/*.* +!assets/manual/man/**/*.md +assets/manual/man.tar.xz diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..fad6c8a --- /dev/null +++ b/Makefile @@ -0,0 +1,36 @@ +PANDOC = pandoc +LATEX = pdflatex +LATEXMK = latexmk +LUA = luajit + +MANUAL_ROOT = assets/manual + +MAN_PATH = $(MANUAL_ROOT)/man +MAN_SRCS = $(wildcard $(MAN_PATH)/*/*.md) +MAN_DSTS = $(MAN_SRCS:%.md=%) +MAN_TEXS = $(MAN_SRCS:%.md=%.tex) + +TEX_PATH = $(MANUAL_ROOT)/tex +MAN_TEX = $(TEX_PATH)/man.tex +TEX_MAIN_SRCS = $(wildcard $(TEX_PATH)/*manual.tex) +TEX_MAIN_DSTS = $(TEX_MAIN_SRCS:%.tex=%.pdf) + +all: doc + +doc: doc-pdf doc-man + +doc-pdf: $(TEX_MAIN_DSTS) +%.pdf:: %.tex $(MAN_TEX) + $(LATEXMK) -cd -pdf $< + +doc-man: $(MAN_DSTS) + find assets/manual/man -regex '.*/[^.]+\.[^.]+$$' | tar -cJf ${MANUAL_ROOT}/man.tar.xz -T - + +%:: %.md + $(PANDOC) -s -t man -o $@ $< + +$(MAN_TEX): $(MAN_TEXS) + find $(MAN_PATH) -name '*.tex' -printf '\\input{../man/%P}\n' | sort > $(MAN_TEX) + +%.tex:: %.md + $(PANDOC) -L ${MANUAL_ROOT}/filter_man_md2tex.lua -t latex -o $@ $< diff --git a/assets/manual/acceleration-distance.ps b/assets/manual/acceleration-distance.ps deleted file mode 100644 index 56fe8b8..0000000 --- a/assets/manual/acceleration-distance.ps +++ /dev/null @@ -1,64 +0,0 @@ -%!PS - -/Courier 12 selectfont -1 setlinewidth - -/pagewidth 595 def -/pageheight 842 def -/entrywidth 25 def -/entryheight 15 def -/nrows 25 def -/ncols 22 def - -/dupsecond { - exch dup 3 1 roll -} def - -/duptwo { - dupsecond dupsecond -} def - -/movetorc { - exch entrywidth mul pagewidth entrywidth ncols mul sub 2 idiv add - exch entryheight mul pageheight entryheight nrows mul sub 2 idiv add pageheight exch sub - moveto -} def - -/integer-string { - dup abs 1 add log floor 2 add cvi string cvs -} def - -/showint { - integer-string show -} def - -/get-acceleration { - 2 mul 3 1 roll dup mul exch dup mul sub exch div ceiling cvi -} def - -<< /PageSize [pagewidth pageheight]>> setpagedevice - -[ -10 -3 -2 -0.5 0.5 1 1.5 ] -{ - dup 0 eq - { pop } - { - -1 1 21 { - dup 0 exch newpath movetorc -1 -4 rmoveto 22 entrywidth mul 0 rlineto closepath stroke - 1 add 0 movetorc -1 11 rmoveto 0 -22 entryheight mul rlineto closepath stroke - } for - newpath 22 21 movetorc -1 -4 rmoveto 0 -3 entryheight mul rlineto -22 entrywidth mul 0 rlineto 0 3 entryheight mul rlineto closepath stroke - 0 1 20 { - dup dup 1 add 0 movetorc showint - dup dup 1 add 0 exch movetorc showint - 0 1 20 { - dupsecond duptwo 1 add exch 1 add exch movetorc 3 index get-acceleration 0 dupsecond lt {showint} {pop} ifelse - } for - pop - } for - 0 22 movetorc (Acc. =) show 2 22 movetorc 5 string cvs show - 0 23 movetorc (The horizontal axis stands for the current speed.) show - 0 24 movetorc (The vertical axis stands for the target speed.) show - showpage - } ifelse -} forall diff --git a/assets/manual/dev-advtrains.tex b/assets/manual/dev-advtrains.tex deleted file mode 100644 index 6b0c0bb..0000000 --- a/assets/manual/dev-advtrains.tex +++ /dev/null @@ -1,79 +0,0 @@ -\part{Developer's Manual} - -This part is mostly relevant only to those interested in working on internal mechanisms of \advtrains{} or making mods related to \advtrains{}. Please note that this part is still incomplete. - -\section{The \texttt{advtrains} table}\label{s:tadvtrains} - -\subsection{Railway time}\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{apidoc}{Railway time adaptation mode} -\item \apienum{independent} Do not adapt to real-life time and instead keep in sync with \advtrains{}' internal dtime. -\item \apienum{follow\_real} Independent of real-life time, but counts up in real-life time. -\item \apienum{adapt\_real} Use \texttt{os.time} for RWT. -\end{apidoc} - -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. -\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}). -\item As a number: the number of seconds since \texttt{0;0;0}. -\end{itemize} - -For a railway time object \texttt{$c$;$m$;$s$}, the following properties are expected to apply: -\begin{itemize} -\item $c \in \mathbb{Z}$, -\item $m \in \mathbb{Z} \cap \left[0,60\right)$, and -\item $s \in \mathbb{Z} \cap \left[0,60\right)$ -\end{itemize} -It is an error if at least one of the above properties do not apply. - -The following entries are present in \texttt{advtrains.interlocking.rwt}. \var{Time}, \var{t}, \var{interval}, and \var{offset} refer to a railway time object represented in one of the methods described above. \var{Interval} and \var{offset} represent the interval and offset of a repetition, respectively. \var{Cycles}, \var{minutes}, and \var{seconds} should be the value of the \texttt{c}, \texttt{m} and \texttt{s} fields of a railway time table. - -\begin{apidoc}{\texttt{advtrains}!\texttt{interlocking.rwt}} -\item \apifunc{add}{\vari{t},\varii{t}} Returns \( t_1 + t_2 \). -\item \apifunc{copy}{\var{time}} Returns a copy of \var{time}. -\item \apifunc{diff}{\vari{t},\varii{t}} Returns \( t_2 - t_1 \) in seconds. -\item \apifunc{last\_rpt}{\varzero{t},\var{interval},\var{offset}} Returns $t$ in the range \( (t_0-\text{\var{interval}},t_0] \) such that \( t = n \cdot \text{\var{interval}} + \text{\var{offset}} \) for \( n \in \mathbb{Z} \). -\item \apifunc{new}{\var{cycles},\var{minutes},\var{seconds}} Returns a railway time table. -\item \apifunc{next\_rpt}{\varzero{t},\var{interval},\var{offset}} Returns $t$ in the range \( [t_0,t_0+\text{\var{interval}}) \) such that \( t = n \cdot \text{\var{interval}} + \text{\var{offset}} \) for \( n \in \mathbb{Z} \). -\item \apifunc{now}{} Returns a table corresponding to the current railway time. -\item \apifunc{sub}{\vari{t},\varii{t}} Returns \( t_1 - t_2 \) in seconds. -\item \apifunc{time\_from\_last\_rpt}{\varzero{t},\var{interval},\var{offset}} Returns $t$ in the range \( [0,\text{\var{interval}}) \) such that \( t_0 - t = n \cdot \text{\var{interval}} + \text{\var{offset}} \) for \( n \in \mathbb{Z} \). -\item \apifunc{time\_to\_next\_rpt}{\varzero{t},\var{interval},\var{offset}} Returns $t$ in the range \( [0,\text{\var{interval}}) \) such that \( t_0 + t = n \cdot \text{\var{interval}} + \text{\var{offset}} \) for \(n \in \mathbb{Z} \). -\item \apifunc{to\_table}{\var{time}} Returns a railway time table corresponding to \var{time}. -\item \apifunc{to\_secs}{\var{time},\ovar{cycles}} Returns the railway time in number representation corresponding to \var{time}. \var{Cycles} is used as the number of cycles, if present. -\item \apifunc{to\_string}{\var{time},\ovar{no cycle}} Returns a railway time string corresponding to \var{time}. If \var{no cycle} is true, the number of cycles is omitted from the return value. -\end{apidoc} - -\subsection{\texttt{advtrains.speed}}\label{s:tspeed} -The \texttt{speed} library allows comparison of speed limits, which can be represented with: -\begin{itemize} -\item $v \geq 0$, which stands for a speed restriction of $v$. -\item $-1$ or \luanil, which lifts the speed restriction. -\end{itemize} -The use of other values (in particular, \luanan{} and $\pm\infty$) may result in undefined behavior. - -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. - -For speed limits, it is said that $a < b$ if $a$ is more strict than $b$, and $a = b$ if $a$ and $b$ refer to the same speed limit. - -The following entries are present in \texttt{advtrains.speed}: - -\begin{apidoc}{\texttt{advtrains}!\texttt{speed}} -\item \apifunc{lessp}{\var{a},\var{b}} Returns a boolean indicating whether $a < b$. -\item \apifunc{greaterp}{\var{a},\var{b}} Returns a boolean indicating whether $a > b$. -\item \apifunc{equalp}{\var{a},\var{b}} Returns a boolean indicating whether $a = b$. -\item \apifunc{not\_lessp}{\var{a},\var{b}} Returns a boolean indicating whether $a \ge b$. -\item \apifunc{not\_greaterp}{\var{a},\var{b}} Returns a boolean indicating whether $a \le b$. -\item \apifunc{not\_equalp}{\var{a},\var{b}} Returns a boolean indicating whether $a \ne b$. -\item \apifunc{min}{\var{a},\var{b}} Returns the strictest limit of \var{a} and \var{b}. -\item \apifunc{max}{\var{a},\var{b}} Returns the less strict limit of \var{a} and \var{b}. -\item \apifunc{set\_restriction}{\var{train},\var{type},\var{val}} Set speed restriction of type \var{type} of \var{train} to \var{val} and update the \texttt{speed\_restriction} field of \var{train} accordingly. \var{Type} defaults to \texttt{main}. -\item \apifunc{merge\_aspect}{\var{train},\var{asp}} Merge the signal aspect \var{asp} into the speed restriction table of \var{train} and update the \texttt{speed\_restriction} field of \var{train} accordingly. -\end{apidoc} - -%%% Local Variables: -%%% TeX-master: "a4manual" -%%% End:
\ No newline at end of file diff --git a/assets/manual/filter_man_md2tex.lua b/assets/manual/filter_man_md2tex.lua new file mode 100644 index 0000000..baa5c00 --- /dev/null +++ b/assets/manual/filter_man_md2tex.lua @@ -0,0 +1,28 @@ +return { + { + Str = function(elem) + if elem.text == "Advtrains" then + return pandoc.RawInline("latex", "\\advtrains{}") + end + end + }, + { + Header = function(elem) + return pandoc.Header(elem.level+1, elem.content) + end, + }, + { + Pandoc = function(elem) + local outputfn = PANDOC_STATE.output_file or error("No output file specified") + local pgname, pgsection = outputfn:match("([^%./\\]+)%.([^%.]+)%.tex$") + assert(pgname and pgsection, "Cannot fetch manpage name and section") + local blocks = elem.blocks + local titlestr = string.format("%s(%s)", pgname, pgsection) + local titleid = string.format("man:%s.%s", pgname, pgsection) + local titleobj = pandoc.Header(1, pandoc.Code(titlestr)) + titleobj.identifier = titleid + blocks:insert(1, titleobj) + return elem + end, + }, +} diff --git a/assets/manual/man/man3advtrains/rwt_add.3advtrains.md b/assets/manual/man/man3advtrains/rwt_add.3advtrains.md new file mode 100644 index 0000000..ec73e9c --- /dev/null +++ b/assets/manual/man/man3advtrains/rwt_add.3advtrains.md @@ -0,0 +1,20 @@ +% RWT_ADD(3ADVTRAINS) | Advtrains Developer's Manual + +# NAME +`add`, `diff`, `sub` - Add or subtract railway time objects + +# SYNOPSIS + +* `add(t1, t2)` +* `diff(t1, t2)` +* `sub(t1, t2)` + +# DESCRIPTION + +* `add()` returns the result of adding `t1` and `t2`. +* `diff()` returns the result of subtracting `t1` from `t2`. +* `sub()` returns the result of subtracting `t2` from `t1`. + +# RETURN VALUE + +`add()` and `sub()` return their results as tables. `diff()` returns its result as a number. diff --git a/assets/manual/man/man3advtrains/rwt_copy.3advtrains.md b/assets/manual/man/man3advtrains/rwt_copy.3advtrains.md new file mode 100644 index 0000000..99dfaf1 --- /dev/null +++ b/assets/manual/man/man3advtrains/rwt_copy.3advtrains.md @@ -0,0 +1,28 @@ +% RWT_COPY(3ADVTRAINS) | Advtrains Developer's Manual + +# NAME +`copy`, `new`, `to_table`, `to_secs`, `to_string` - Create and copy railway time objects + +# SYNOPSIS + +* `copy(obj)` +* `new(cycles, minutes, seconds)` +* `to_table(obj)` +* `to_secs(obj [, cycles])` +* `to_string(obj [, no_cycles])` + +# DESCRIPTION + +* `copy()` returns a copy of `obj`. +* `new()` creates a new railway time object with the given number of cycles, minutes, and seconds. +* `to_table()`, `to_secs()`, and `to_string()` convert `obj` to a table, number, or string, respectively. If `cycles` is passed to `to_secs()`, that value is used as the number of cycles. If `no_cycles` is passed to `to_string()`, the number of cycles is set to zero. + +# RETURN VALUE + +* `copy()` returns the copy that is created. If `obj` is a table, the returned value is not identical to `obj`. +* `new()` returns the newly created object as a table. +* `to_table()`, `to_secs()`, `to_string()` returns the conveerted object. + +# NOTES + +`to_table()` returns `obj` if it is a table. diff --git a/assets/manual/man/man3advtrains/rwt_last_rpt.3advtrains.md b/assets/manual/man/man3advtrains/rwt_last_rpt.3advtrains.md new file mode 100644 index 0000000..0336820 --- /dev/null +++ b/assets/manual/man/man3advtrains/rwt_last_rpt.3advtrains.md @@ -0,0 +1,19 @@ +% RWT_LAST_RPT(3ADVTRAINS) | Advtrains Developer's Manual + +# NAME +`last_rpt`, `next_rpt`, `time_from_last_rpt`, `time_to_next_rpt` - Calculate time for repeating events + +# SYNOPSIS + +* `last_rpt(time, interval, offset)` +* `next_rpt(time, interval, offset)` +* `time_from_last_rpt(interval, offset)` +* `time_to_next_rpt(interval, offset)` + +# DESCRIPTOIN +The functions described in this page calculates the time or time difference related to events scheduled to repeat with the given interval and at the given offset, in relation to the given time. Whether and when the event actually takes place is not relevant to the API. + +* `last_rpt()` returns the time at which the event was expected to occur the last time +* `next_rpt()` returns the time at which the event is expected to occur the next time +* `time_from_last_rpt()` returns the time since the event was expected to occur the last time +* `time_to_next_rpt()` return the time until the event is expected to occur the next time diff --git a/assets/manual/man/man3advtrains/rwt_now.3advtrains.md b/assets/manual/man/man3advtrains/rwt_now.3advtrains.md new file mode 100644 index 0000000..0843b1f --- /dev/null +++ b/assets/manual/man/man3advtrains/rwt_now.3advtrains.md @@ -0,0 +1,7 @@ +% RWT_NOW(3ADVTRAINS) | Advtrains Developer's Manual + +# NAME +`now` - Get the current railway time + +# DESCRIPTION +`now()` returns the current railway time as a table. diff --git a/assets/manual/man/man7advtrains/rwt.7advtrains.md b/assets/manual/man/man7advtrains/rwt.7advtrains.md new file mode 100644 index 0000000..5e04d5e --- /dev/null +++ b/assets/manual/man/man7advtrains/rwt.7advtrains.md @@ -0,0 +1,24 @@ +% RWT(7ADVTRAINS) | Advtrains Developer's Manual + +# NAME +`rwt` - Advtrains railway time + +# DESCRIPTION +Advtrains depends on Minetest's "dtime" for most operations, and may slow itself down when necessary to prevent unexpected behavior, such as in a situation with a significant amount of lag. 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 and, with this information, implementing a scheduling system. It can, however, also be set up to keep in sync with real-life time. + +Railway time is counted in cycles, minutes, and seconds, roughly corresponding to their real-life counterparts, with cycles roughly corresponding to hours. For a valid railway time object, it is expected that + +* The "cycles" element is an integer, +* The "minutes" element is an integer between 0 and 59 (inclusive), and +* The "seconds" element is an integer between 0 and 59 (inclusive). + +Railway time may be represented in three formats: + +* As a table with the `c`, `m`, `s` fields holding the cycles, minutes, and seconds, respectively, +* As a string with the cycles, minutes and seconds delimited with a semicolon, +* For zero cycles, as a string with the minutes and seconds delimited with a semicolon, or +* As a number representing the number of seconds since 0;0;0. + +If railway time is represented as a string, each element may have a variable length and do not require padding zeroes, and an element of the string may be empty if it is at the beginning or the end of the string. + +The railway time API is available in the `advtrains.interlocking.rwt` table or, for LuaATC, in the `rwt` table. diff --git a/assets/manual/a4manual.tex b/assets/manual/tex/a4manual.tex index 08d8c84..08d8c84 100644 --- a/assets/manual/a4manual.tex +++ b/assets/manual/tex/a4manual.tex diff --git a/assets/manual/a5manual.tex b/assets/manual/tex/a5manual.tex index 31af590..31af590 100644 --- a/assets/manual/a5manual.tex +++ b/assets/manual/tex/a5manual.tex diff --git a/assets/manual/contributing.tex b/assets/manual/tex/contributing.tex index 9b7d53b..9b7d53b 100644 --- a/assets/manual/contributing.tex +++ b/assets/manual/tex/contributing.tex diff --git a/assets/manual/tex/dev-advtrains.tex b/assets/manual/tex/dev-advtrains.tex new file mode 100644 index 0000000..4bfbeab --- /dev/null +++ b/assets/manual/tex/dev-advtrains.tex @@ -0,0 +1,36 @@ +\part{Developer's Manual} + +This part is mostly relevant only to those interested in working on internal mechanisms of \advtrains{} or making mods related to \advtrains{}. Please note that this part is still incomplete. + +\section{The \texttt{advtrains} table}\label{s:tadvtrains} + +\subsection{\texttt{advtrains.speed}}\label{s:tspeed} +The \texttt{speed} library allows comparison of speed limits, which can be represented with: +\begin{itemize} +\item $v \geq 0$, which stands for a speed restriction of $v$. +\item $-1$ or \luanil, which lifts the speed restriction. +\end{itemize} +The use of other values (in particular, \luanan{} and $\pm\infty$) may result in undefined behavior. + +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. + +For speed limits, it is said that $a < b$ if $a$ is more strict than $b$, and $a = b$ if $a$ and $b$ refer to the same speed limit. + +The following entries are present in \texttt{advtrains.speed}: + +\begin{apidoc}{\texttt{advtrains}!\texttt{speed}} +\item \apifunc{lessp}{\var{a},\var{b}} Returns a boolean indicating whether $a < b$. +\item \apifunc{greaterp}{\var{a},\var{b}} Returns a boolean indicating whether $a > b$. +\item \apifunc{equalp}{\var{a},\var{b}} Returns a boolean indicating whether $a = b$. +\item \apifunc{not\_lessp}{\var{a},\var{b}} Returns a boolean indicating whether $a \ge b$. +\item \apifunc{not\_greaterp}{\var{a},\var{b}} Returns a boolean indicating whether $a \le b$. +\item \apifunc{not\_equalp}{\var{a},\var{b}} Returns a boolean indicating whether $a \ne b$. +\item \apifunc{min}{\var{a},\var{b}} Returns the strictest limit of \var{a} and \var{b}. +\item \apifunc{max}{\var{a},\var{b}} Returns the less strict limit of \var{a} and \var{b}. +\item \apifunc{set\_restriction}{\var{train},\var{type},\var{val}} Set speed restriction of type \var{type} of \var{train} to \var{val} and update the \texttt{speed\_restriction} field of \var{train} accordingly. \var{Type} defaults to \texttt{main}. +\item \apifunc{merge\_aspect}{\var{train},\var{asp}} Merge the signal aspect \var{asp} into the speed restriction table of \var{train} and update the \texttt{speed\_restriction} field of \var{train} accordingly. +\end{apidoc} + +%%% Local Variables: +%%% TeX-master: "a4manual" +%%% End:
\ No newline at end of file diff --git a/assets/manual/interlocking.tex b/assets/manual/tex/interlocking.tex index d5398ae..d5398ae 100644 --- a/assets/manual/interlocking.tex +++ b/assets/manual/tex/interlocking.tex diff --git a/assets/manual/introduction.tex b/assets/manual/tex/introduction.tex index 1e782a0..1351fbf 100644 --- a/assets/manual/introduction.tex +++ b/assets/manual/tex/introduction.tex @@ -11,7 +11,7 @@ A notable portion of the manual is influenced by various other guides and manual \item The format of the API documentation is influenced by R$^7$RS. \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} +\item The manuals related to railway-time are modifed from 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} diff --git a/assets/manual/luaatc.tex b/assets/manual/tex/luaatc.tex index 500a8a7..10a67e8 100644 --- a/assets/manual/luaatc.tex +++ b/assets/manual/tex/luaatc.tex @@ -128,7 +128,7 @@ The following are available if \texttt{advtrains\_interlocking} is enabled. \end{apidoc} \subsection{Railway time} -the railway time API described in section \ref{s:tilrwt} is available in the \texttt{rwt} table. +Please refer to \manref{rwt}{7advtrains} for information on the railway time API. \begin{apidoc}{LuaATC} \item \apifunc{schedule}{\var{time},\var{message}} Triggers a \texttt{schedule} event at \var{time} with the message \var{message}. Only one event can be scheduled this way. \item \apifunc{schedule\_in}{\var{time},\var{message}} Like \texttt{schedule}, but \var{time} is given as the time until the event is triggered. diff --git a/assets/manual/main.tex b/assets/manual/tex/main.tex index 89c96c7..17d327d 100644 --- a/assets/manual/main.tex +++ b/assets/manual/tex/main.tex @@ -7,6 +7,7 @@ \include{signals.tex} \include{luaatc.tex} +\include{manpages.tex} \include{dev-advtrains.tex} \include{nodedef.tex} \include{tables.tex} diff --git a/assets/manual/tex/manpages.tex b/assets/manual/tex/manpages.tex new file mode 100644 index 0000000..3ef817d --- /dev/null +++ b/assets/manual/tex/manpages.tex @@ -0,0 +1,7 @@ +\part{Manual Pages} +\input{man.tex} + +%%% Local Variables: +%%% mode: LaTeX +%%% TeX-master: "a4manual" +%%% End:
\ No newline at end of file diff --git a/assets/manual/nodedef.tex b/assets/manual/tex/nodedef.tex index 04a409e..04a409e 100644 --- a/assets/manual/nodedef.tex +++ b/assets/manual/tex/nodedef.tex diff --git a/assets/manual/physics.tex b/assets/manual/tex/physics.tex index 5df11f9..5df11f9 100644 --- a/assets/manual/physics.tex +++ b/assets/manual/tex/physics.tex diff --git a/assets/manual/preamble.tex b/assets/manual/tex/preamble.tex index aaee8c8..567b16d 100644 --- a/assets/manual/preamble.tex +++ b/assets/manual/tex/preamble.tex @@ -51,6 +51,9 @@ \newcommand{\vari}[1]{\varnth{#1}{1}} \newcommand{\varii}[1]{\varnth{#1}{2}} +\newcommand{\manref}[2]{\hyperref[man:#1.#2]{\texttt{#1(#2)}}} +\def\tightlist{} % pandoc compat + \def\luatrue{\texttt{true}} \def\luafalse{\texttt{false}} \def\luanil{\texttt{nil}} diff --git a/assets/manual/tex/screenshot.png b/assets/manual/tex/screenshot.png new file mode 120000 index 0000000..ad2460b --- /dev/null +++ b/assets/manual/tex/screenshot.png @@ -0,0 +1 @@ +../../../screenshot.png
\ No newline at end of file diff --git a/assets/manual/signals.tex b/assets/manual/tex/signals.tex index 53da702..53da702 100644 --- a/assets/manual/signals.tex +++ b/assets/manual/tex/signals.tex diff --git a/assets/manual/tables.tex b/assets/manual/tex/tables.tex index 91422b6..91422b6 100644 --- a/assets/manual/tables.tex +++ b/assets/manual/tex/tables.tex diff --git a/assets/manual/title.tex b/assets/manual/tex/title.tex index ad2b1a2..5430979 100644 --- a/assets/manual/title.tex +++ b/assets/manual/tex/title.tex @@ -3,7 +3,7 @@ \begin{tikzpicture}[remember picture,overlay] \newcommand{\HUGE}[1]{\scalebox{2}{\Huge #1}} \fill[Turquoise] (current page.south west) rectangle (current page.north east); - \node [below,inner sep=0,outer sep=0,name=coverimage] at (current page.north) {\includegraphics[width=2\paperwidth]{../../screenshot.png}}; + \node [below,inner sep=0,outer sep=0,name=coverimage] at (current page.north) {\includegraphics[width=2\paperwidth]{screenshot.png}}; \draw ($0.5*(coverimage.south)+0.5*(current page.south)$) +(0,0.5) node [above] {\HUGE{Advanced Trains}} +(0,-0.5) node [below] {\HUGE{for Minetest}}; diff --git a/assets/manual/tracks.tex b/assets/manual/tex/tracks.tex index 9e0bb6d..9e0bb6d 100644 --- a/assets/manual/tracks.tex +++ b/assets/manual/tex/tracks.tex diff --git a/assets/manual/train-controls.tex b/assets/manual/tex/train-controls.tex index 4a09ab6..4a09ab6 100644 --- a/assets/manual/train-controls.tex +++ b/assets/manual/tex/train-controls.tex |
