Adding help text for junction and station signals

[Matthew]

I looked in the on-line in-game help for information about station signals, but I could not find any. So I have adapted Ves' text from the .dat documentation as a possible addition to the 'Signals Usage' helpfile. Is this accurate and easy to understand?:


<­em>Station signals<­/em>

Station signals may be available for the "time interval" and "absolute block" methods, depending upon the pakset.  One station signal controls all of the station's platforms and it can be placed anywhere on any of those platforms.<­br><­br>

Station signals will clear only if another train has not departed in the same direction from any platform within 5 minutes (or such other time as may have been specified in simuconf.tab for time interval signals). Only one station signal is needed for all platforms, since the station signal is per definition bidirectional and will work in either direction. The station signal in "time interval with telegraph" mode will additionally not clear unless it can make a directional reservation. In principle, station signals in plain time interval mode should also not clear unless the sighting-distance number of tiles beyond the station are clear.<­br><­br>

The station signals are most suited to small stations or stations on single track lines. Larger stations would better suit basic stop signals at the end of each platform.<­br><­br>

Also note that a station signal does not signal <it>towards</it> the station: you will still need a choose signal.<­br><­br>


I have never used station signals in the Swedish pakset, so I have no idea whether this describes them accurately or not.

Ves, are you happy for your text to be released under the Artistic Licence?

Also, there is no mention of junction signals. Would the following changes (in red) to the 'Working Methods' helpfile be an improvement? I have also tidied up the spelling and grammar.


<­em>Time interval signalling<­/em><­br>
Time interval signalling works by telling the approaching train how long time ago since the last train passed the signal. Therefore, they show clear by default and will work like this:<­br>
- Clear by default<­br>
- Danger on the passage of a train<­br>
- Caution 5 (in-game) minutes after a train had passed. Trains approaching the signal may continue beyond it at half line speed or half the signal's sighting speed, whichever is the lower<­br>
- Clear 10 (in-game) minutes after a train had passed<­br><­br>

If a time interval stop signal (including a railway policeman) is placed in front of a junction, it will never show clear, because the signal operator does not know whether a train may have entered the track from another direction. Trains will therefore continue at reduced speeds after a junction until they encounter the next signal.<­br><­br>

Be aware that this working method also very easily creates deadlocks. If trains collide in this working method, both trains will come to an emergency stop for a short time before continuing in the drive by sight working method.<­br>
Also, the choose signals have some choose functionality, but be careful to avoid deadlocks at terminus stations.<­br>
Time interval signalling is best used on double tracked lines with trains that run at roughly the same speed. It is not possible to create bidirectional signals using time interval signals.<­br><­br>


In pak128.Britain-Ex, the emergency stop time is about 2 minutes. That seems like a short time to me, in the context of a game that lasts two and a half centuries! 

[Mariculous]

First, your link is broken.

In principle, station signals in plain time interval mode should also not clear unless the sighting-distance number of tiles beyond the station are clear.

In principle? So they should behave like that but don't?

You should also mention the directional reservations created by time interval station signals in some cases, not sure about absolute block station signals as these don't exist in Pak128.Britain-Ex.

I can confirm that it is easy to understand.

Furthermore, as both informations are addressed to players, the wiki help about signalling should be as consistent to ingame help as possible, which means it should have the same structure and same texts where possible.
Ves dat file reference is more about

Wiki help should contain information about all signal types generally available in extended, where ingame help should take the same text, add pakset specific informations and remove sections not being relevant to the pakset where possible.
This would make it much easier for players to switch from one pakset to another.

Also, in the railway tools signal information (mouseover hover text), in addition to the signals working method, signals should also show all of the other _relevant_ attributes such as "stop signal"(is_signal), "presignal"(is_presignal), "directional reservation"(is_longblocksignal), "choose signal"(free_route), "permissive", "intermediate_block" "two block"(double_block) "oneway"(single_way) "private gate"(is_private) "end of choose"(end_of_choose) and "aspects:n"
Only attributes listed should be displayed. Aspects should only be displayed when it is not 2.

This would ensure that players changing from one pakset to another could associate an "absolute block, stop signal" to work just exactly as a Semaphore stop signal, no matter if it is called "some crazy signal that works in a normal way" or not.

[Ves]

Hello, sorry for my absense lately...
Thanks for looking into the text's!

I have no problem whatsoever with you using what I have written and transforming it into something better. I think what you wrote in red makes perfectly sense, thanks! The text about the station signals would need to be updated to accommodate absolute block, though, but that should be easy.

After I created the initial helptext documents those years ago, I have been thinking back and forth how to best categorize the information in the text's. The current four (or five?) pages is not nearly enough to really describe all aspects of the signalling. An obvious way would be to categorize it by working methods, with the drawback that the amount of pages would drasticly increase (one page for each working method) as well as riscs of double information.
Alternatively it could be categorized by "signal-types", such like "choose signals", "station signals", "distant signals", and then describe how each of those signals works in each working method on their respective page.
Personally, I am leaning towards the "working method" categorization, though.

Also, the texts are lacking alot of information, simply because I didnt fully understand how all signals worked when I first wrote the pages. I mostly took James descriptions and wrote them out, mixing them with ingame observations. This, combined with new added signals (station signals and double block signals) along with changed functionallity, leads unfortunately to some fuzzy descriptions and inconsistent information. If I had written them today, they probably would have been much different

"In principle" I seem to remember being my wording, and it comes from the fact that I was told that it should work, but I for some reason could not get it to work, probably due to some bugs, and therefore that was the wording I came up with at the time.
You are right, it should be much more definite, to help the player understand the complex mechanism's across paksets.

Speaking of different paksets, the Swedish pakset currently has some signals which the British one doesnt, and that is the Absolute block station signal, Double block signal as well as the combination of the both. Also it has is_longblocksignal=1 on all track circuit signals so they all create directional reservations even for single faced signals.



Reading your OP inspired me to rethink the documents.
I would propose the following pages:

1 Signal overview:
General points on how signals works, along with links to all of the other pages:
* Concept of how signals fundamentally differs from Simutrans Standard (Sighting distance; many needs signalboxes; no signal=drive by sight; etc)
* Concept of working methods
* Concept of signalboxes
* Concept of some of the major signal features (choose signals, permissive signals, distant signals, station signals etc)
* Concept of the different types of reservations a signal can make (currently only "red" and "blue").
* Concept of automatic signalupgrade.
* ...

2 Signal help:
A help page where some of the most basic questions are answered:
* How do you build a signal
* How do you reassign a signal to a new signalbox
* How do you create a bidirectional signal (when possible)
* ...

3 Signalboxes:
This page displays all details regarding signalboxes.
This page should also be the page that is displayed when clicking the question mark from a signalbox info window.
* Describe the specific signalbox features ("signals" and "radius")
* How to build signals using the signalbox
* How to check if a particular signal is connected to the signalbox
* How to see the radius of the signalbox marked on the ground
* How to reassign signals to a different signalbox
* ...

4 Signs:
This page describes the different signs that can be placed along the railway.

5 Signal tips and tricks:
Pretty self explanatory, this page would give the players some tips on how to optimize their signal layout.
* How to best space signals for maximum capacity on the tracks
* Best locations for signalboxes
* Brief summary on what signals and working methods would be best for different situations (and different eras). Examples could be:
* - Small mainline station
* - Single dead end
* - A line with only one track
* ...

And then a page for each working method, thoroughly describing each working method and patiently going through all the different kinds of signal variants that exists in each working method. Also some tips on where to put the signals and where not to put them.
6 Drive by sight
7 Time interval
8 Time interval with telegraph
9 One train staff
10 Token block
11 Absolute block
12 Track circuit block
13 Cab signalling
14 Moving block

As far as I know there is no way to have pakset specific help texts, so the texts would have to be written to accomodate all variants, even if some pakset doesnt have a particular variant.

What do you think? What more would be needed/desired?

[Mariculous]

I like that structure, at a first view it looks better ordered.


For the wiki or the forums, I would additionally suppose to use ingame screenshots visualizing signal workings, as this is much easyer to anderstand than a plain text but not possible in ingame help.
Also, don't forget to link to James great videos.

If it is not possible to create pakset specific help texts, it is even much more important to show mentioned additional signal attributes in the mouseover information as we can't refer from the help texts to actual signals by their name since these are different in different paksets.
I have just forked Simutrans-extended on github and will have a look at the code. Can't imagine adding these attributes to a string is pretty difficult.

[Ves]

No it probably isnt very dificult, although locating it in the code is worse. I stumbled upon it some times when I was looking for something else, but I have forgotten where it was....

The problem with showing all the attributes in the tooltip display is that the tooltip gets pretty long. Perhaps some short terms could be come up with to ease with that, for instance DI = distant signal, CH = choose signal, ST = station signal, PE = permissive signal etc? Those should of corse be reflected in the help texts as well!

[Mariculous]

Well, most signals do only have one or two additional attributes, so it would not be a huge problem.
Additionally, I was thinking about using newlines if possible, but don't know yet if this is possible for these tooltips.

It should be a structure like this (not final)
signal/sign_name[", Distance: "distance]
construction_cost, maintainance_cost
"Max speed: "max_speed[", Min speed: "min_speed]
working_method[", Aspects: "aspects]
attributes

Where text in brackets is optional, that means only shown if set for that sign and attributes is a list of all additionaly defined attributes for that sign/signal:
"stop signal", "presignal", "directional reservation", "choose signal", "permissive", "intermediate_block", "two block", "oneway", "private gate" and "end of choose".
Maybe I forgot some.

However, I don't know yet how to properly handle naming of these attributes.
I don't want to take attribute names from the dat file, as some of them are hard to understand and it would not be translated to any other language.
I don't want to use pak dependant translation files, as different translations between paksets would not help a user switching between paksets.
I don't want to hardcode translations as this is generally a bad idea.
The best way would be pakset independent translation files, but I don't think these exist in Simutrans do they?
Alternatively we have to use pak dependant translation files and a signal attribute naming convention.

[Elemental]

Another great usability addition would be if the tooltip for building signalboxes would list the (currently) available signal types, and their range. When I was new to extended, in the brithish pakset, I often placed mechanical signalboxes (maximum distance ~4km?) and wondered why I could not place the signals that far away - because the signals available for a long time only allow for 1250m distance or something like that, and only the automatic and light signals introduced decades later can actually use the full range of the signalbox.

[Matthew]

First, your link is broken.

Apologies, that has been corrected, but for convenience here it is again: https://forum.simutrans.com/index.php/topic,14848.msg146541.html#msg146541

In principle? So they should behave like that but don't?

Ves has already answered this above, I think.

You should also mention the directional reservations created by time interval station signals in some cases, not sure about absolute block station signals as these don't exist in Pak128.Britain-Ex.

The proposed text already mentions that directional reservations can be made by station signals using the "time interval with telegraph" working method. The proposed text states everything I know, as I have only used this working method for the first time this week. I know that all the required information is in the code, but the block reserver code is very complex (because signalling is a very complex problem!). Does anyone have more information about these directional reservations?

I can confirm that it is easy to understand.

That is helpful feedback; thank you.

Furthermore, as both informations are addressed to players, the wiki help about signalling should be as consistent to ingame help as possible, which means it should have the same structure and same texts where possible. ...

Wiki help should contain information about all signal types generally available in extended, where ingame help should take the same text, add pakset specific informations and remove sections not being relevant to the pakset where possible.
This would make it much easier for players to switch from one pakset to another.

I agree that the information should be consistent, because both should be consistent with the game code!  As others have said, the current reality is that it is the other way around: in-game files are pakset-independent; the wiki has multiple pages for different paksets.

On the same point:

As far as I know there is no way to have pakset specific help texts, so the texts would have to be written to accomodate all variants, even if some pakset doesnt have a particular variant.

I am reminded of the Wikipedia principle of WP:NOTPAPER. Since the helpfiles are only ⩽10kB in a download of 1GB+, it seems to me that that adding extra pakset-specific helpfiles, accessed through the main index or by a pakset-specific button, would be an unconditional improvement.

Also, in the railway tools signal information (mouseover hover text), in addition to the signals working method, signals should also show all of the other _relevant_ attributes such as "stop signal"(is_signal), "presignal"(is_presignal), "directional reservation"(is_longblocksignal), "choose signal"(free_route), "permissive", "intermediate_block" "two block"(double_block) "oneway"(single_way) "private gate"(is_private) "end of choose"(end_of_choose) and "aspects:n"
Only attributes listed should be displayed. Aspects should only be displayed when it is not 2.

This is one of many interesting ideas in this thread that I will leave to others to pursue...

Hello, sorry for my absense lately...
Thanks for looking into the text's!

This is a hobby; people appearing and disappearing is as normal as steam engine pistons going in and out...

I have no problem whatsoever with you using what I have written and transforming it into something better. I think what you wrote in red makes perfectly sense, thanks!

Thank you for agreeing to release the text and for all the documentation that you have provided for the signalling.

The text about the station signals would need to be updated to accommodate absolute block, though, but that should be easy.

<snip>

Speaking of different paksets, the Swedish pakset currently has some signals which the British one doesnt, and that is the Absolute block station signal, Double block signal as well as the combination of the both. Also it has is_longblocksignal=1 on all track circuit signals so they all create directional reservations even for single faced signals.

I have amended the proposed text in red at the end of this post to try to address absolute block more completely based on your feedback, the .dat file and a helpful guide to historical Swedish signals that I found online. Do you think this is now a helpful and accurate guide to the Swedish pakset, please?

"In principle" I seem to remember being my wording, and it comes from the fact that I was told that it should work, but I for some reason could not get it to work, probably due to some bugs, and therefore that was the wording I came up with at the time.
You are right, it should be much more definite, to help the player understand the complex mechanism's across paksets.

It seems to me that this code is still buggy (though vastly improved since 2015), so you were right then and are still right.

Reading your OP inspired me to rethink the documents.
I would propose the following pages:

Again, there are many interesting points here for you and others to pursue...


<­em>Station signals<­/em>

Station signals may be available for the "time interval" and "absolute block" methods, depending upon the pakset.  One station signal controls all of the station's platforms and trains departing in any direction. It can be placed anywhere on any of those platforms.<­br><­br>

When using the "time interval" and "time interval with telegraph" working methods, station signals will clear only if another train has not departed in the same direction from any platform within 5 minutes (or such other time as has been set as time_interval_seconds_to_clear may have been specifiedin simuconf.tab or the settings dialoguefor time interval signals). Only one station signal is needed for all platforms, since the station signal is per definition bidirectional and will work in either direction. The station signal in "time interval with telegraph" mode will additionally not clear unless it can make a directional reservation. In principle, station signals in plain "time interval" mode should also not clear unless the sighting-distance number of tiles beyond the station are clear. There is also a pakset with a special variant of the station signal that only allows trains to depart if it can reserve two blocks ahead.<­br><­br>

If a pakset has a station signal for the "absolute block" working method, then station signals will clear only if the desired block has not been reserved by another train. Such paksets usually have a variant of the station signal that only allows trains to depart if the signal can reserve two blocks ahead. <­br><­br>

The station signals are most suited to small stations or stations on single track lines. Larger stations would better suit basic stop signals at the end of each platform.<­br><­br>

Also note that a station signal does not signal <it>towards</it> the station: you will still need a choose or stop signal to control trains entering the station.<­br><­br>

[Ves]

I think this line is a bit weird and a bit misleading:

"There is also a pakset with a special variant of the station signal that only allows trains to depart if it can reserve two blocks ahead"

Actually I am not sure if there actually needs to be such an explanation. There should be a section about double block reservation anyway, and it should be fairly straight forward for the player to understand a signal "double block" and "station signal" together if they know what they are separately and how they work from before hand. If there where to be special rules that applied to that combination, that should of corse be explaned.
Instead, it should be a general princip that not all combinations of features exists in every pakset, and that should be emphasized early on I think.

This line:

"If a pakset has a station signal for the "absolute block" working method, then station signals will clear only if the desired block has not been reserved by another train. Such paksets usually have a variant of the station signal that only allows trains to depart if the signal can reserve two blocks ahead"

... I think you should write like you wrote about the time interval version, something like this (feel free to adjust);

"There is also an absolute block station signal which will clear in the same way like a normal absolute block signal would. If a train holds at any platform and the path is free for it up until the following signal, the absolute block station signal will clear. If the station signal is also a double block station signal, it will only clear when the following two blocks are free."

But as I mentioned, I would actually like to rearrange the entire help text section completely, making it more easy to understand and more obvious to add ammendments in the future (hopefully). What do you think of the outline I proposed?