Reformat manual pages

12 files changed, 106 insertions, 62 deletions

diff --git a/Makefile b/Makefile
index ba1a371..3d05472 100644
--- a/Makefile
+++ b/Makefile
@@ -30,8 +30,8 @@ doc-man: $(MAN_DSTS)
 %:: %.md ${MAN_FILTER}
 	$(PANDOC) -L ${MAN_FILTER} -s -t man -o $@ $<
 
-$(MAN_TEX): $(MAN_TEXS)
-	find $(MAN_PATH) -name '*.tex' -printf '\\input{../man/%P}\n' | sort > $(MAN_TEX)
-
 %.tex:: %.md ${MAN_FILTER}
 	$(PANDOC) -L ${MAN_FILTER} -t latex -o $@ $<
+
+$(MAN_TEX): $(MAN_TEXS)
+	find $(MAN_PATH) -name '*.tex' -printf '\\input{../man/%P}\n' | sort > $(MAN_TEX)
diff --git a/assets/manual/filter_man.lua b/assets/manual/filter_man.lua
index bdb1b33..e80442b 100644
--- a/assets/manual/filter_man.lua
+++ b/assets/manual/filter_man.lua
@@ -1,3 +1,5 @@
+local text, utils = pandoc.text, pandoc.utils
+
 local filters = {}
 
 local function add_filter(x)
@@ -9,21 +11,36 @@ local is_man = FORMAT:match "man"
 
 add_filter {
 	Pandoc = function(elem)
+		local blocks, meta = elem.blocks, elem.meta
+
+		local page_title = utils.stringify(meta.title)
+		local page_manual = utils.stringify(meta.manual)
+		local page_name, page_section = page_title:match("^([^%(]+)%(([^%)]+)%)$")
+
+		-- add page title
+		meta.title = pandoc.MetaString(string.format("%s | %s", text.upper(page_title), page_manual))
+		if is_latex then
+			local titleid = string.format("man:%s.%s", page_name, page_section)
+			local titleobj = pandoc.Header(1, pandoc.Code(page_title))
+			titleobj.identifier = titleid
+			blocks:insert(1, titleobj)
+		end
+
+		-- add "See Also" section
 		local seealso = elem.meta.seealso
 		if not seealso then
-			return
+			return elem
 		end
-		local blocks = elem.blocks
-		blocks:insert(pandoc.Header(1, pandoc.Str("SEE ALSO")))
+		blocks:insert(pandoc.Header(1, pandoc.Str("See Also")))
 		if is_man then
 			for k, v in pairs(seealso) do
-				seealso[k] = v[1].text
+				seealso[k] = utils.stringify(v)
 			end
 			blocks:insert(pandoc.Plain(table.concat(seealso, ", ")))
 		else
 			local list = {}
 			for _, i in ipairs(seealso) do
-				local page = i[1].text
+				local page = utils.stringify(i)
 				local pgname, pgsection = string.match(page, "^([^%)]+)%(([^%)]+)%)$")
 				local item = pandoc.Plain(page)
 				if is_latex and pgname and pgsection then
@@ -48,25 +65,30 @@ if is_latex then
 	}
 	add_filter {
 		Header = function(elem)
+			if (elem.identifier or ""):match("^man:") then
+				return elem -- do not modify title header
+			end
 			local attr = {
 				class = "unnumbered unlisted",
 			}
 			return pandoc.Header(elem.level+1, elem.content, attr)
 		end,
 	}
+end
+
+if is_man then
 	add_filter {
-		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,
+		Header = function(elem)
+			local filter = {
+				Str = function(elem)
+					return pandoc.Str(text.upper(elem.text))
+				end,
+				Code = function(elem)
+					return pandoc.Str(elem.text)
+				end,
+			}
+			return pandoc.walk_block(elem, filter)
+		end
 	}
 end
 
diff --git a/assets/manual/man/man3advtrains/rwt_add.3advtrains.md b/assets/manual/man/man3advtrains/rwt_add.3advtrains.md
index ec73e9c..de4cf37 100644
--- a/assets/manual/man/man3advtrains/rwt_add.3advtrains.md
+++ b/assets/manual/man/man3advtrains/rwt_add.3advtrains.md
@@ -1,20 +1,23 @@
-% RWT_ADD(3ADVTRAINS) | Advtrains Developer's Manual
+---
+title: 'rwt_add(3advtrains)'
+manual: 'Advtrains Developer''s Manual'
+---
 
-# NAME
+# Name
 `add`, `diff`, `sub` - Add or subtract railway time objects
 
-# SYNOPSIS
+# Synopsis
 
 * `add(t1, t2)`
 * `diff(t1, t2)`
 * `sub(t1, t2)`
 
-# DESCRIPTION
+# 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
+# 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
index 99dfaf1..1d2ba28 100644
--- a/assets/manual/man/man3advtrains/rwt_copy.3advtrains.md
+++ b/assets/manual/man/man3advtrains/rwt_copy.3advtrains.md
@@ -1,9 +1,12 @@
-% RWT_COPY(3ADVTRAINS) | Advtrains Developer's Manual
+---
+title: 'rwt_copy(3advtrains)'
+manual: 'Advtrains Developer''s Manual'
+---
 
-# NAME
+# Name
 `copy`, `new`, `to_table`, `to_secs`, `to_string` - Create and copy railway time objects
 
-# SYNOPSIS
+# Synopsis
 
 * `copy(obj)`
 * `new(cycles, minutes, seconds)`
@@ -11,18 +14,18 @@
 * `to_secs(obj [, cycles])`
 * `to_string(obj [, no_cycles])`
 
-# DESCRIPTION
+# 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
+# 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
+# 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
index 0336820..db5bad5 100644
--- a/assets/manual/man/man3advtrains/rwt_last_rpt.3advtrains.md
+++ b/assets/manual/man/man3advtrains/rwt_last_rpt.3advtrains.md
@@ -1,16 +1,19 @@
-% RWT_LAST_RPT(3ADVTRAINS) | Advtrains Developer's Manual
+---
+title: 'rwt_last_rpt(3advtrains)'
+manual: 'Advtrains Developer''s Manual'
+---
 
-# NAME
+# Name
 `last_rpt`, `next_rpt`, `time_from_last_rpt`, `time_to_next_rpt` - Calculate time for repeating events
 
-# SYNOPSIS
+# Synopsis
 
 * `last_rpt(time, interval, offset)`
 * `next_rpt(time, interval, offset)`
 * `time_from_last_rpt(interval, offset)`
 * `time_to_next_rpt(interval, offset)`
 
-# DESCRIPTOIN
+# 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
diff --git a/assets/manual/man/man3advtrains/rwt_now.3advtrains.md b/assets/manual/man/man3advtrains/rwt_now.3advtrains.md
index 0843b1f..0f52258 100644
--- a/assets/manual/man/man3advtrains/rwt_now.3advtrains.md
+++ b/assets/manual/man/man3advtrains/rwt_now.3advtrains.md
@@ -1,7 +1,10 @@
-% RWT_NOW(3ADVTRAINS) | Advtrains Developer's Manual
+---
+title: 'rwt_now(3advtrains)'
+manual: 'Advtrains Developer''s Manual'
+---
 
-# NAME
+# Name
 `now` - Get the current railway time
 
-# DESCRIPTION
+# Description
 `now()` returns the current railway time as a table.
diff --git a/assets/manual/man/man3advtrains/speed_lessp.3advtrains.md b/assets/manual/man/man3advtrains/speed_lessp.3advtrains.md
index 5bc61e7..af1319f 100644
--- a/assets/manual/man/man3advtrains/speed_lessp.3advtrains.md
+++ b/assets/manual/man/man3advtrains/speed_lessp.3advtrains.md
@@ -1,9 +1,12 @@
-% SPEED_LESSP(3ADVTRAINS) | Advtrains Developer's Manual
+---
+title: 'speed_lessp(3advtrains)'
+manual: 'Advtrains Developer''s Manual'
+---
 
-# NAME
+# Name
 `lessp`, `greaterp`, `equalp`, `not_lessp`, `not_greaterp`, `not_equalp`, `min`, `max` - Speed limit comparison functions
 
-# SYNOPSIS
+# Synopsis
 
 * `lessp(a, b)`
 * `greaterp(a, b)`
@@ -13,7 +16,7 @@
 * `min(a, b)`
 * `max(a, b)`
 
-# DESCRIPTION
+# Description
 `lessp()`, `greaterp()`, `equalp()`, `not_lessp()`, `not_greaterp()`, and `not_equalp()` are predicate functions that returns, respectively,
 
 * Whether `a` is more strict than `b`
diff --git a/assets/manual/man/man3advtrains/speed_set_restriction.3advtrains.md b/assets/manual/man/man3advtrains/speed_set_restriction.3advtrains.md
index 1df5358..1a3bd80 100644
--- a/assets/manual/man/man3advtrains/speed_set_restriction.3advtrains.md
+++ b/assets/manual/man/man3advtrains/speed_set_restriction.3advtrains.md
@@ -1,17 +1,20 @@
-% SPEED_SET_RESTRICTION(3ADVTRAINS) | Advtrains Developer's Manual
+---
+title: 'speed_set_restriction(3advtrains)'
+manual: 'Advtrains Developer''s Manual'
+---
 
-# NAME
+# Name
 `set_restriction`, `merge_aspect` - Apply speed limits to trains
 
-# SYNOPSIS
+# Synopsis
 
 * `set_restriction(train, type, val)`
 * `merge_aspect(train, asp)`
 
-# DESCRIPTION
+# 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
+# Return Value
 `set_restriction()` and `merge_aspect()` do not return any value.
diff --git a/assets/manual/man/man7advtrains/node_definition.7advtrains.md b/assets/manual/man/man7advtrains/node_definition.7advtrains.md
index c662614..8b6407a 100644
--- a/assets/manual/man/man7advtrains/node_definition.7advtrains.md
+++ b/assets/manual/man/man7advtrains/node_definition.7advtrains.md
@@ -1,23 +1,24 @@
 ---
-title: 'NODE_DEFINITION(7ADVTRAINS) | Advtrains Developer''s Manual'
+title: 'node_definition(7advtrains)'
+manual: 'Advtrains Developer''s Manual'
 seealso:
 - signal_aspects(7advtrains)
 ---
 
-# NAME
+# Name
 `node_definition` - Advtrains-specific node definition entries
 
-# DESCRIPTION
+# Description
 This page describes various fields in node definition tables that are used by Advtrains.
 
-# NODE GROUPS
+# 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
 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.
diff --git a/assets/manual/man/man7advtrains/rwt.7advtrains.md b/assets/manual/man/man7advtrains/rwt.7advtrains.md
index 5e15406..3c1690a 100644
--- a/assets/manual/man/man7advtrains/rwt.7advtrains.md
+++ b/assets/manual/man/man7advtrains/rwt.7advtrains.md
@@ -1,5 +1,6 @@
 ---
-title: 'RWT(7ADVTRAINS) | Advtrains Developer''s Manual'
+title: 'rwt(7advtrains)'
+manual: 'Advtrains Developer''s Manual'
 seealso:
 - rwt_add(3advtrains)
 - rwt_copy(3advtrains)
@@ -7,10 +8,10 @@ seealso:
 - rwt_now(3advtrains)
 ---
 
-# NAME
+# Name
 `rwt` - Advtrains railway time
 
-# DESCRIPTION
+# 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
diff --git a/assets/manual/man/man7advtrains/signal_aspects.7advtrains.md b/assets/manual/man/man7advtrains/signal_aspects.7advtrains.md
index 0066f7f..110d642 100644
--- a/assets/manual/man/man7advtrains/signal_aspects.7advtrains.md
+++ b/assets/manual/man/man7advtrains/signal_aspects.7advtrains.md
@@ -1,13 +1,14 @@
 ---
-title: 'SIGNAL_ASPECTS(7ADVTRAINS) | Advtrains Developer''s Manual'
+title: 'signal_aspects(7advtrains)'
+manual: 'Advtrains Developer''s Manual'
 seealso:
 - speed(7advtrains)
 ---
 
-# NAME
+# Name
 `signal_aspects` - Signal aspect tables for Advtrains
 
-# DESCRIPTION
+# 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:
diff --git a/assets/manual/man/man7advtrains/speed.7advtrains.md b/assets/manual/man/man7advtrains/speed.7advtrains.md
index eefd764..b963686 100644
--- a/assets/manual/man/man7advtrains/speed.7advtrains.md
+++ b/assets/manual/man/man7advtrains/speed.7advtrains.md
@@ -1,15 +1,16 @@
 ---
-title: 'SPEED(7ADVTRAINS) | Advtrains Developer''s Manual'
+title: 'speed(7advtrains)'
+manual: 'Advtrains Developer''s Manual'
 seealso:
 - speed_lessp(3advtrains)
 - speed_set_restriction(3advtrains)
 - signal_aspects(7advtrains)
 ---
 
-# NAME
+# Name
 `speed` - Advtrains speed limit library
 
-# DESCRIPTION
+# 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
@@ -19,6 +20,6 @@ The use of other values (in particular, nan and infinity) may result in undefine
 
 This library is available as `advtrains.speed`.
 
-# NOTES
+# 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.