Use ldoc instead of manpages

.build.yml

@@ -6,6 +6,7 @@ packages:
 - unzip
 - wget
 - lua-busted
+- lua-ldoc
 - pandoc
 - texlive-extra-utils
 - texlive-latex-base
@@ -19,7 +20,7 @@ sources :
 artifacts:
 - .minetest/mods/advtrains/assets/manual/tex/a4manual.pdf
 - .minetest/mods/advtrains/assets/manual/tex/a5manual.pdf
-- .minetest/mods/advtrains/assets/manual/man.tar.xz
+- .minetest/mods/advtrains/assets/manual/ldoc.tar.xz
 
 tasks:
 

.gitignore

@@ -6,11 +6,7 @@ assets/manual/tex/*.*
 assets/manual/tex/auto
 !assets/manual/tex/*.tex
 !assets/manual/tex/screenshot.png
-assets/manual/tex/man.tex
 assets/manual/tex/_region_*
-assets/manual/tex/man/*.*
-!assets/manual/tex/man/.gitkeep
 
-assets/manual/man/**/*.*
+assets/manual/ldoc_output
-!assets/manual/man/**/*.md
+assets/manual/ldoc.tar.xz
-assets/manual/man.tar.xz

Makefile

@@ -1,37 +1,22 @@
-PANDOC = pandoc
+LATEXMK = latexmk -cd -pdf -interaction=nonstopmode
-LATEXMK = latexmk -cd -pdf -silent
-LUA = luajit
 
 MANUAL_ROOT = assets/manual
 
-MAN_PATH = $(MANUAL_ROOT)/man
+LUA_SRCS = $(wildcard advtrains*/*.lua)
-MAN_SRCS = $(wildcard $(MAN_PATH)/*/*.md)
-MAN_DSTS = $(MAN_SRCS:%.md=%)
-MAN_TEXS = $(MAN_SRCS:%.md=%.tex)
-MAN_FILTER = $(MANUAL_ROOT)/filter_man.lua
 
 TEX_PATH = $(MANUAL_ROOT)/tex
-MAN_TEX_DIR = $(TEX_PATH)/man
+TEX_ALL_SRCS = $(wildcard $(TEX_PATH)/*.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: doc-pdf doc-ldoc
 
 doc-pdf: $(TEX_MAIN_DSTS)
-%.pdf: %.tex $(MAN_TEX) $(wildcard $(TEX_PATH)/*.tex)
+%.pdf:: %.tex $(TEX_ALL_SRCS)
 	$(LATEXMK) $<
 
-doc-man: $(MAN_DSTS)
+doc-ldoc:: $(LUA_SRCS)
-	find assets/manual/man -regex '.*/[^.]+\.[^.]+$$' | tar -cJf ${MANUAL_ROOT}/man.tar.xz -T -
+	ldoc .
-
+	tar cJf assets/manual/ldoc.tar.xz -C assets/manual/ldoc_output .
-%:: %.md ${MAN_FILTER}
-	$(PANDOC) -L ${MAN_FILTER} -s -t man -o $@ $<
-
-%.tex:: %.md ${MAN_FILTER}
-	$(PANDOC) -L ${MAN_FILTER} -t latex -o $(MAN_TEX_DIR)/$(notdir $@) $<
-
-$(MAN_TEX): $(MAN_TEXS)
-	find $(MAN_TEX_DIR) -name '*.tex' -printf '\\include{man/%f}\n' | sort | sed '1s/^\\include/\\input/' > $(MAN_TEX)

advtrains/atc.lua

@@ -128,7 +128,8 @@ advtrains.atc_function = function(def, preset, suffix, rotation)
 				local meta=minetest.get_meta(pos)
 				if meta then
 					if not fields.save then 
-						--[[--maybe only the dropdown changed
+						--[[
+						--maybe only the dropdown changed
 						if fields.mode then
 							meta:set_string("mode", idxtrans[fields.mode])
 							if fields.mode=="digiline" then

advtrains/speed.lua

@@ -1,5 +1,17 @@
--- auxiliary functions for the reworked speed restriction system
+--- Auxiliary functions for the reworked speed restriction system.
+-- For this library, the speed limit may be represented using
+--
+-- * A non-negative number representing a speed limit in m/s
+-- * `-1` or `nil`, which lifts the speed limit
+--
+-- The use of other values (in particular, `nan` and `inf`) may result in undefined behavior.
+--
+-- Please note the difference between the meaning of `nil` in this library and in signal aspect tables.
 
+--- Check if `a` is more strict than `b`
+-- @function lessp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_lessp(a, b)
 	if not a or a == -1 then
 		return false
@@ -10,26 +22,50 @@ local function s_lessp(a, b)
 	end
 end
 
+--- Check if `a` is less strict than `b`
+-- @function greaterp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_greaterp(a, b)
 	return s_lessp(b, a)
 end
 
+--- Check if `a` is not more strict than `b`
+-- @function not_lessp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_not_lessp(a, b)
 	return not s_lessp(a, b)
 end
 
+--- Check if `a` is not less strict than `b`
+-- @function not_greaterp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_not_greaterp(a, b)
 	return not s_greaterp(a, b)
 end
 
+--- Check if `a` and `b` represent equivalent speed limits
+-- @function equalp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_equalp(a, b)
 	return (a or -1) == (b or -1)
 end
 
+--- Check if `a` and `b` do not represent equivalent speed limits
+-- @function not_equalp
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_not_equalp(a, b)
 	return (a or -1) ~= (b or -1)
 end
 
+--- Returns the speed limit that is less strict
+-- @function max
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_max(a, b)
 	if s_lessp(a, b) then
 		return b
@@ -38,6 +74,10 @@ local function s_max(a, b)
 	end
 end
 
+--- Returns the speed limit that is more strict
+-- @function min
+-- @param a an object representing a speed limit
+-- @param b an object representing a speed limit
 local function s_min(a, b)
 	if s_lessp(a, b) then
 		return a
@@ -46,6 +86,8 @@ local function s_min(a, b)
 	end
 end
 
+--- Returns the strictest speed limit in a table
+-- @param tbl a table of speed limits
 local function get_speed_restriction_from_table (tbl)
 	local strictest = -1
 	for _, v in pairs(tbl) do
@@ -57,6 +99,10 @@ local function get_speed_restriction_from_table (tbl)
 	return strictest
 end
 
+--- Update a value in the speed limit table
+-- @param tbl the `speed_restriction` field of a train table
+-- @param rtype the type of speed limit
+-- @param rval the speed limit of the given type
 local function set_speed_restriction (tbl, rtype, rval)
 	if rval then
 		tbl[rtype or "main"] = rval
@@ -64,12 +110,21 @@ local function set_speed_restriction (tbl, rtype, rval)
 	return tbl
 end
 
+--- Set the speed limit of a train
+-- @function set_restriction
+-- @param train the train object
+-- @param rtype the type of speed limit
+-- @param rval the speed limit of the given type
 local function set_speed_restriction_for_train (train, rtype, rval)
 	local t = train.speed_restrictions_t or {main = train.speed_restriction}
 	train.speed_restrictions_t = set_speed_restriction(t, rtype, rval)
 	train.speed_restriction = get_speed_restriction_from_table(t)
 end
 
+--- Set the speed limit of a train based on a signal aspect
+-- @function merge_aspect
+-- @param train the train object
+-- @param asp the signal aspect table
 local function merge_speed_restriction_from_aspect_to_train (train, asp)
 	return set_speed_restriction_for_train(train, asp.type, asp.main)
 end

advtrains/trainlogic.lua

@@ -562,7 +562,7 @@ function advtrains.train_step_b(id, train, dtime)
 		train.acceleration = 0
 	end
 	
-	--- 3b. if braking, modify the velocity BEFORE the movement
+	--- 3b. if braking, modify the velocity BEFORE the movement ---
 	if braking then
 		local dv = advtrains.get_acceleration(train, lever) * dtime
 		local v1 = v0 + dv
@@ -671,7 +671,7 @@ function advtrains.train_step_b(id, train, dtime)
 	recalc_end_index(train)
 	--atprint("in train_step_b: New index",train.index,"end",train.end_index,"vel",train.velocity)
 	
-	--- 4a. if accelerating, modify the velocity AFTER the movement
+	--- 4a. if accelerating, modify the velocity AFTER the movement ---
 	if accelerating then
 		local dv = advtrains.get_acceleration(train, lever) * dtime
 		local v1 = v0 + dv
@@ -715,7 +715,7 @@ function advtrains.train_step_c(id, train, dtime)
 	local train_moves=(train.velocity~=0)
 	local very_short_train = train.trainlen < 3
 
-	--- On-track collision handling - detected in train_step_b, but handled here so all other train movements have already happened.
+	-- On-track collision handling - detected in train_step_b, but handled here so all other train movements have already happened. --
 	if train.ontrack_collision_info then
 		train.velocity = 0
 		train.acceleration = 0

advtrains_line_automation/stoprail.lua

@@ -3,7 +3,7 @@
 
 
 local function to_int(n)
-	--- Disallow floating-point numbers
+	-- Disallow floating-point numbers
 	local k = tonumber(n)
 	if k then
 		return math.floor(k)

advtrains_luaautomation/environment.lua

@@ -1,5 +1,6 @@
 -------------
--- lua sandboxed environment
+-- LuaATC sandboxed environment
+-- @module atlatc
 
 -- function to cross out functions and userdata.
 -- modified from dump()
@@ -354,7 +355,7 @@ end
 -- env.subscribers table may be directly altered by callers.
 
 
---- class interface
+-- class interface
 
 function atlatc.env_new(name)
 	local newenv={

advtrains_train_track/init.lua

@@ -140,9 +140,9 @@ minetest.register_craft({
 		{'advtrains:dtrack_placer', '', 'advtrains:dtrack_placer'}
 	}
 })
----- Not included: very shallow crossings like (30/60)+45.
+-- Not included: very shallow crossings like (30/60)+45.
----- At an angle of only 18.4 degrees, the models would not
+-- At an angle of only 18.4 degrees, the models would not
----- translate well to a block game.
+-- translate well to a block game.
 -- END crossings
 
 --slopes

assets/manual/man/man3advtrains/rwt_add.3advtrains.md

@@ -1,25 +0,0 @@
----
-titles:
-- rwt_add
-- rwt_diff
-- rwt_sub
-section: 3advtrains
-manual: 'Advtrains Developer''s Manual'
-shortdesc: 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.

assets/manual/man/man3advtrains/rwt_copy.3advtrains.md

@@ -1,35 +0,0 @@
----
-titles:
-- rwt_copy
-- rwt_new
-- rwt_to_table
-- rwt_to_secs
-- rwt_to_string
-section: 3advtrains
-manual: 'Advtrains Developer''s Manual'
-shortdesc: 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.

assets/manual/man/man3advtrains/rwt_last_rpt.3advtrains.md

@@ -1,25 +0,0 @@
----
-titles:
-- rwt_last_rpt
-- rwt_next_rpt
-- rwt_time_from_last_rpt
-- rwt_time_to_next_rpt
-section: 3advtrains
-manual: 'Advtrains Developer''s Manual'
-shortdesc: 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)`
-
-# Description
-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

assets/manual/man/man3advtrains/rwt_now.3advtrains.md

@@ -1,10 +0,0 @@
----
-titles:
-- rwt_now
-section: 3advtrains
-manual: 'Advtrains Developer''s Manual'
-shortdesc: get the current railway time
----
-
-# Description
-`now()` returns the current railway time as a table.

assets/manual/man/man3advtrains/speed_lessp.3advtrains.md

@@ -1,36 +0,0 @@
----
-titles:
-- speed_lessp
-- speed_greaterp
-- speed_equalp
-- speed_not_lessp
-- speed_not_greaterp
-- speed_not_equalp
-- speed_min
-- speed_max
-section: 3advtrains
-manual: 'Advtrains Developer''s Manual'
-shortdesc: compare speed limits
----
-
-# Synopsis
-
-* `lessp(a, b)`
-* `greaterp(a, b)`
-* `equalp(a, b)`
-* `not_lessp(a, b)`
-* `not_greaterp(a, b)`
-* `min(a, b)`
-* `max(a, b)`
-
-# Description
-`lessp()`, `greaterp()`, `equalp()`, `not_lessp()`, `not_greaterp()`, and `not_equalp()` are predicate functions that returns, respectively,
-
-* Whether `a` is more strict than `b`
-* Whether `a` is less strict than `b`
-* Whether `a` and `b` indicate the same speed limit
-* Whether `a` is not more strict than `b`
-* Whether `a` is nor less strict than `b`
-* Whether `a` and `b` do not indicate the same speed limit
-
-`min()` returns the speed limit that is more strict. `max()` returns the speed limit that is less strict.

assets/manual/man/man3advtrains/speed_set_restriction.3advtrains.md

@@ -1,21 +0,0 @@
----
-titles:
-- speed_set_restriction
-- speed_merge_aspect
-section: 3advtrains
-manual: 'Advtrains Developer''s Manual'
-shortdesc: apply speed limits to trains
----
-
-# Synopsis
-
-* `set_restriction(train, type, val)`
-* `merge_aspect(train, asp)`
-
-# Description
-`set_restriction()` sets the speed restriction of the given type of the given train to `val` and updates train object correspondingly.
-
-`merge_aspect()` sets the speed restriction of the given train based on the value of the signal aspect.
-
-# Return Value
-`set_restriction()` and `merge_aspect()` do not return any value.

assets/manual/man/man7advtrains/node_definition.7advtrains.md

@@ -1,28 +0,0 @@
----
-titles:
-- node_definition
-section: 7advtrains
-manual: 'Advtrains Developer''s Manual'
-shortdesc: node definition entries specific to Advtrains
-seealso:
-- signal_aspects(7advtrains)
----
-
-# 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.

assets/manual/man/man7advtrains/rwt.7advtrains.md

@@ -1,32 +0,0 @@
----
-titles:
-- rwt
-section: 7advtrains
-manual: 'Advtrains Developer''s Manual'
-shortdesc: Advtrains railway time
-seealso:
-- rwt_add(3advtrains)
-- rwt_copy(3advtrains)
-- rwt_last_rpt(3advtrains)
-- rwt_now(3advtrains)
----
-
-# 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.

assets/manual/man/man7advtrains/signal_aspects.7advtrains.md

@@ -1,26 +0,0 @@
----
-titles:
-- signal_aspects
-section: 7advtrains
-manual: 'Advtrains Developer''s Manual'
-shortdesc: signal aspect tables for Advtrains
-seealso:
-- speed(7advtrains)
----
-
-# 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

assets/manual/man/man7advtrains/speed.7advtrains.md

@@ -1,25 +0,0 @@
----
-titles:
-- speed
-section: 7advtrains
-manual: 'Advtrains Developer''s Manual'
-shortdesc: Advtrains speed limit library
-seealso:
-- speed_lessp(3advtrains)
-- speed_set_restriction(3advtrains)
-- signal_aspects(7advtrains)
----
-
-# Description
-The speed library allows the manipulation of speed limits, which can be represented with
-
-* A non-negative number, which stands for a regular speed limit in m/s, or
-* -1 or `nil`, which lifts the speed restriction
-
-The use of other values (in particular, nan and infinity) may result in undefined behavior.
-
-This library is available as `advtrains.speed`.
-
-# Notes
-
-The meaning of `nil` for the speed limit library differs from its meaning in signal aspect tables, where `nil` keeps the current speed limit.

assets/manual/tex/luaatc.tex

@@ -124,11 +124,11 @@ The following are available if \texttt{advtrains\_interlocking} is enabled.
 \item \apifunc{can\_set\_route}{\var{pos},\var{name}} Returns a boolean indicating whether the route named \var{name} of the signal at \var{pos} can be set.
 \item \apifunc{set\_route}{\var{pos},\var{name}} Sets the route named \var{name} of the signal at \var{pos}.
 \item \apifunc{cancel\_route}{\var{pos}} Cancels the route that is set from the signal at \var{pos}.
-\item \apifunc{get\_aspect}{\var{pos}} Returns the signal aspect of the signal at \var{pos}. Please refer to \manref{signal\string_aspect}{7advtrains} for the structure of signal aspect tables.
+\item \apifunc{get\_aspect}{\var{pos}} Returns the signal aspect of the signal at \var{pos}.
 \end{apidoc}
 
 \subsection{Railway time}
-Please refer to \manref{rwt}{7advtrains} for information on the railway time API.
+Please refer to the railway time API documentation for more information.
 \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.
@@ -194,4 +194,4 @@ The following operations are safe in the approach callback:
 
 %%% Local Variables:
 %%% TeX-master: "a4manual"
-%%% End:
+%%% End:

assets/manual/tex/main.tex

@@ -9,8 +9,6 @@
 
 \include{contributing.tex}
 
-\input{manpages.tex}
-
 \include{physics.tex}
 
 \ifx\HCode\undefined
@@ -20,4 +18,4 @@
 %%% Local Variables:
 %%% mode: LaTeX
 %%% TeX-master: "a4manual"
-%%% End:
+%%% End:

assets/manual/tex/manpages.tex

@@ -1,7 +0,0 @@
-\part{Manual Pages}
-\input{man.tex}
-
-%%% Local Variables:
-%%% mode: LaTeX
-%%% TeX-master: "a4manual"
-%%% End:

assets/manual/tex/preamble.tex

@@ -51,9 +51,6 @@
 \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}}
@@ -202,4 +199,4 @@
 
 %%% Local Variables:
 %%% TeX-master: "a4manual"
-%%% End:
+%%% End:

config.ld

@@ -0,0 +1,7 @@
+all = true
+dir = "assets/manual/ldoc_output"
+format = "markdown"
+merge = true
+project = "Advtrains"
+title = "Advtrains Developer's Manual"
+-- vim: syntax=lua