From 3f6cef730838ed9ab20e445e4078ecc504f1e72e Mon Sep 17 00:00:00 2001 From: ywang Date: Sun, 7 Nov 2021 19:01:45 +0100 Subject: Add documentation on signal aspects --- advtrains/doc/advtrains_speed_lessp.3advtrains.md | 2 +- .../doc/advtrains_speed_merge_aspect.3advtrains.md | 18 ---------------- .../advtrains_speed_set_restriction.3advtrains.md | 18 ++++++++++++++++ advtrains/doc/signal_aspect.7advtrains.md | 24 ++++++++++++++++++++++ 4 files changed, 43 insertions(+), 19 deletions(-) delete mode 100644 advtrains/doc/advtrains_speed_merge_aspect.3advtrains.md create mode 100644 advtrains/doc/advtrains_speed_set_restriction.3advtrains.md create mode 100644 advtrains/doc/signal_aspect.7advtrains.md diff --git a/advtrains/doc/advtrains_speed_lessp.3advtrains.md b/advtrains/doc/advtrains_speed_lessp.3advtrains.md index 165d028..663aa42 100644 --- a/advtrains/doc/advtrains_speed_lessp.3advtrains.md +++ b/advtrains/doc/advtrains_speed_lessp.3advtrains.md @@ -1,4 +1,4 @@ -% advtrains.speed.lessp(3advtrains) | Advtrains Developer's Manual +% advtrains_speed_lessp(3advtrains) | Advtrains Developer's Manual # NAME `advtrains.speed.lessp`, `advtrains.speed.greaterp`, `advtrains.speed.not_lessp`, `advtrains.speed_not_greaterp`, `advtrains.speed.equalp`, `advtrains.speed.not_equalp`, `advtrains.speed.max`, `advtrains.speed.min` - speed restriction comparison functions diff --git a/advtrains/doc/advtrains_speed_merge_aspect.3advtrains.md b/advtrains/doc/advtrains_speed_merge_aspect.3advtrains.md deleted file mode 100644 index 02e83ea..0000000 --- a/advtrains/doc/advtrains_speed_merge_aspect.3advtrains.md +++ /dev/null @@ -1,18 +0,0 @@ -% advtrains.speed.set_restriction(3advtrains) | Advtrains Developer's Manual - -# NAME -`advtrains.speed.set_restriction`, `advtrains.speed.merge_aspect` - modify speed restriction - -# SYNOPSIS -* `advtrains.speed.set_restriction(train, rtype, rval)` -* `advtrains.speed.merge_aspect(train, asp)` - -# DESCRIPTION - -The `advtrains.speed.set_restriction` function sets the speed restriction of type `rtype` of `train` to `rval` and updates the speed restriction value to the strictest speed restriction in the table, or `nil` if all speed restrictions are `nil` or `-1`. If the speed restriction table does not exist, it is created with the `"main"` speed restriction being the speed restriction value of `train`. - -The `advtrains.speed.merge_aspect` function merges the main aspect of `asp` into the speed restriction table with the same procedure described above. If the signal aspect table does not provide the type of speed restriction, the restriction type `"main"` is assumed. - -# SIDE EFFECTS - -Both functions modify `train.speed_restriction` and `train.speed_restrictions_t`. diff --git a/advtrains/doc/advtrains_speed_set_restriction.3advtrains.md b/advtrains/doc/advtrains_speed_set_restriction.3advtrains.md new file mode 100644 index 0000000..b3183c6 --- /dev/null +++ b/advtrains/doc/advtrains_speed_set_restriction.3advtrains.md @@ -0,0 +1,18 @@ +% advtrains_speed_set_restriction(3advtrains) | Advtrains Developer's Manual + +# NAME +`advtrains.speed.set_restriction`, `advtrains.speed.merge_aspect` - modify speed restriction + +# SYNOPSIS +* `advtrains.speed.set_restriction(train, rtype, rval)` +* `advtrains.speed.merge_aspect(train, asp)` + +# DESCRIPTION + +The `advtrains.speed.set_restriction` function sets the speed restriction of type `rtype` of `train` to `rval` and updates the speed restriction value to the strictest speed restriction in the table, or `nil` if all speed restrictions are `nil` or `-1`. If the speed restriction table does not exist, it is created with the `"main"` speed restriction being the speed restriction value of `train`. + +The `advtrains.speed.merge_aspect` function merges the main aspect of `asp` into the speed restriction table with the same procedure described above. If the signal aspect table does not provide the type of speed restriction, the restriction type `"main"` is assumed. + +# SIDE EFFECTS + +Both functions modify `train.speed_restriction` and `train.speed_restrictions_t`. diff --git a/advtrains/doc/signal_aspect.7advtrains.md b/advtrains/doc/signal_aspect.7advtrains.md new file mode 100644 index 0000000..827760d --- /dev/null +++ b/advtrains/doc/signal_aspect.7advtrains.md @@ -0,0 +1,24 @@ +% signal_aspect(7advtrains) | Advtrains Developer's Manual + +# DESCRIPTION + +The signal aspect table used by advtrains has the following fields: + +* `main`: The main speed restriction +* `dst`: The `main` aspect of the distant signal (not implemented) +* `type`: The type of speed restriction given by the signal +* `shunt`: Whether shunting is allowed +* `proceed_as_main`: Whether to proceed without shunting + +The `main` and `dst` fields may contain the following values: +* `-1`: No speed restriction +* `nil`: No information is available + +The `type` field can be any valid table index, but it should usually be one of the following values: +* "main": The main signal aspect used before the introduction of speed restriction types. This is the default value if the `type` field is absent. +* "line": The speed limit for the physical line. +* "temp": The speed limit that is temporarily introduced. + +# NOTES + +A signal with the `main` aspect of zero should not provide distant signal aspect. -- cgit v1.2.3