The International Simutrans Forum

 

Author Topic: SimEx documentation / wiki  (Read 2956 times)

0 Members and 1 Guest are viewing this topic.

Offline zook2

  • *
  • Posts: 321
SimEx documentation / wiki
« on: November 29, 2017, 11:10:08 PM »
It's the time of year when I return yet again to Simutrans to provide 300 years of shoddy, uncomfortable, sporadic and totally mismanaged transport services to all of Britain. I've done this for, hmmm, well over a decade now but I don't consider myself an expert player. Actually, ask me after a year's absence how pre-signals work (or used to work) and I'd be out of my depth; I don't think I ever used them. Schedule shifts? I know where to find the buttons, but I forgot what the feature is good for.

Anyway, this post
https://forum.simutrans.com/index.php?topic=17248.0
got me thinking about something that's been nagging me for quite a while: a coherent documentation of advanced features. If I'm missing something important here, which is quite possible, please excuse me.

Currently, I know the following sources of information:
- the Simutrans Standard wiki (which I don't need)
- the in-game help (which I've rarely looked into because it used to lag a lot behind development)
- this forum (pretty much the only place to find what I was looking for, but almost completely unorganized and a pain in the neck to search through, if I may put it that way)
- James' video tutorials for the new signalling system.

Let's start with the videos: they are very well done and a good primer on a complex  subject, but
a) I lament the modern trend to explain things in YouTube videos. I don't want to spend ten minutes to get information I could read in 30 seconds if somebody had written it down.
b) If I need to look up some detail I've forgotten or not understood correctly I don't want to spend another ten minutes to watch it all again. And again a week later.

What I want is a wiki. Whenever I fire up SimEx I want to keep a browser tab open with the online documentation. I don't care if it's incomplete or some pages are out of date. But it's all in one place and easy to navigate. It can be updated and expanded by member of the community and doesn't require James' time. Over time it can replace all other documentation.

I understand there was a discussion about keeping SimEx-specific info within the relevant  pages of the Standard wiki, but that was a long time ago. I don't think it ever happened (please correct me if I'm wrong) and I guess it would have been an unsatisfactory solution anyway, because it would mix up two games that have grown apart quite significantly over the years.

So, since I have some time on my hands, I'd volunteer for the job of getting this started. For the first time I could actually contribute a little to the game, if someone would set up a SimEx section in the wiki. Or perhaps I could set up a separate one on a free wikihost site somewhere.

I've done something like this before for a different game and when I was done, I'd say it was actually useful. Not 100% complete, not perfect, but good enough both as a place to get an overview, learn the basics and later on look up the advanced stuff whenever you needed to.

Even if I just compiled a list of features and then copied&pasted forum posts, slightly edited them for clarity and added a few cross-links and screenshots, it would be a start.

What do you think?

Offline jamespetts gb

  • Simutrans-Extended project coordinator
  • Moderator
  • *
  • Posts: 18690
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: SimEx documentation / wiki
« Reply #1 on: November 29, 2017, 11:35:44 PM »
Thank you for your offer to help - it is much appreciated. I should note that the in-game help files have been updated quite a bit recently, although are not fully up to date with all of the features yet. I do not have access to the existing wiki, so I am not able to grant you access to that. While you are quite free to start your own Simutrans-Extended wiki, given that the in-game help files already have significant documentation specific to Simutrans-Extended, I do wonder whether doing so would amount to an inefficient duplication of effort that might better be spent keeping the in-game help files up to date.

One approach if there is a strong reason to prefer a web based approach (for example, if it is easier in a multi-monitor setup to have one monitor with Simutrans-Extended and the other with the web page with the wiki) might be simply to replicate the help files in wiki form, and then update both at the same time. In principle, it should be possible automatically to transfer the content of one to another, but I am not sure whether anyone with the expertise to do that is able to assist. The trouble with doing it manually will be that the in-game help files have their own markup that would be very time consuming to strip manually for a web-based wiki.

Incidentally, as to the videos, these are especially useful for the signalling as showing how things actually work is likely to be easier to understand than explaining it in writing for some of the fairly complex concepts in signalling.

In any event, any assistance that you are able to render as regards documentation would be much appreciated.

Offline zook2

  • *
  • Posts: 321
Re: SimEx documentation / wiki
« Reply #2 on: November 30, 2017, 12:05:55 AM »
Thanks. I just had a look at the help text files, and I think wikifying them wouldn't be too much of a problem. I didn't know they were updated, however a wiki documentation would have a few more advantages IMO:

- anyone could contribute, expand or fix errors, without checking files into the github repository (which would be too much of a hassle anyway, especially for smaller edits)
- what you add/edit is online immediately
- you can add images (!)
- better readability, esp. on smaller screens (IMO)
- possibility to add links to external docs, i.e. the forum or YouTube

I'd be interested in what the others think about this, especially new players.

Offline jamespetts gb

  • Simutrans-Extended project coordinator
  • Moderator
  • *
  • Posts: 18690
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: SimEx documentation / wiki
« Reply #3 on: November 30, 2017, 01:59:43 AM »
Thank you for that feedback - that is useful. I see that a wiki does have some advantages, although I am still concerned about possible duplication of effort and some information being in the in-game help files and some in the wiki and the two never both having everything at once.

Can you think of a sensible, long-term solution to this issue?

Offline Frank

  • Inactive/Retired
  • *
  • Posts: 1431
  • Languages: DE
Re: SimEx documentation / wiki
« Reply #4 on: November 30, 2017, 05:48:37 AM »
You can almost easily start creating pages for Simutrans-Extented in the wiki.

wiki help

The organization can be done via categories or structures.

Categories should be possible by any registered user.

Structures require additional rights. But I can create the structure for you or maintain the pages there.
If you dare to do it yourself, I can give you the appropriate rights.



And the help files can also be set in the translator. All registered users can also make changes there. Unregistered people can make suggestions.

This possibility has been postponed elsewhere.

The translator also creates an online readable version of the help.

Offline Ves

  • Devotee
  • *
  • Posts: 1664
  • Languages: EN, SV, DK
Re: SimEx documentation / wiki
« Reply #5 on: November 30, 2017, 09:16:26 AM »
What a great idea! How about making it possible to download the entire wiki so player can update the help pages in the game them self?
Also, whenever the game is compiled, it grabs the newest version from the wiki to be put in the game (automatically or manually by the developer).

The workflow would then be:
- write something on the wiki
- a note is (automatically?) sent to players somehow to update their help files
- players manually updates their help files, alternatively just waits for the newest version of the game to be released.

I know that the pages of the help files are hard coded in the game, if they are not just linking to each other. This could be a trouble if someone wants to add a new page on a subject, but it will then not show up in the help window.

I did some pages a while ago about signals and how to use them. I even have a page under construction, still only on my computer, which would give some concrete examples of in which situations to use what signals.
Feel free to use any of those pages, and you could even split them up into smaller pages. Some of them are lacking information (ie, on absolute block, I think).

Offline zook2

  • *
  • Posts: 321
Re: SimEx documentation / wiki
« Reply #6 on: November 30, 2017, 10:45:40 AM »
You can almost easily start creating pages for Simutrans-Extented in the wiki.

wiki help

The organization can be done via categories or structures.

Categories should be possible by any registered user.

Structures require additional rights. But I can create the structure for you or maintain the pages there.
If you dare to do it yourself, I can give you the appropriate rights.

Thanks! I've had a look at structures at the tikiwiki site. Apparently it's not like namespaces in other wiki systems. So you would create e.g. the
"en_Index_SimExtended (English Simutrans Extended (formerly Sim Experimental) Wiki)" structure as a top page and give me the rights to create and move sub-pages within the structure, without having to worry about mucking up the rest of the wiki?

If you'd create an account for me, I'd give it a try.

Quote
And the help files can also be set in the translator. All registered users can also make changes there. Unregistered people can make suggestions.
This possibility has been postponed elsewhere.
The translator also creates an online readable version of the help.
I'd rather not get into this myself. Two construction sites at one time is too much at the moment.

Offline zook2

  • *
  • Posts: 321
Re: SimEx documentation / wiki
« Reply #7 on: November 30, 2017, 11:09:18 AM »
What a great idea! How about making it possible to download the entire wiki so player can update the help pages in the game them self?
Also, whenever the game is compiled, it grabs the newest version from the wiki to be put in the game (automatically or manually by the developer).

The workflow would then be:
- write something on the wiki
- a note is (automatically?) sent to players somehow to update their help files
- players manually updates their help files, alternatively just waits for the newest version of the game to be released.

I know that the pages of the help files are hard coded in the game, if they are not just linking to each other. This could be a trouble if someone wants to add a new page on a subject, but it will then not show up in the help window.

While this might be possible, it is not what I have in mind at the moment. All I intend to do at the beginning is to collect information from the forum (or users like you) that is more detailed than what's available in the help files, and dump it in the wiki for ease of reference. Once it's there it can slowly be expanded and kneaded into shape.

Offline jamespetts gb

  • Simutrans-Extended project coordinator
  • Moderator
  • *
  • Posts: 18690
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: SimEx documentation / wiki
« Reply #8 on: November 30, 2017, 11:45:16 AM »
Frank - that is interesting: I did not know about the online viewing of in-game help files. Is there a way to do this separately for Simutrans-Extended's help files at present? If not, it would be helpful if that could exist.

Offline Frank

  • Inactive/Retired
  • *
  • Posts: 1431
  • Languages: DE
Re: SimEx documentation / wiki
« Reply #9 on: November 30, 2017, 05:18:22 PM »
...
If you'd create an account for me, I'd give it a try.
....

You can register yourself.

For page names I think en_extended_page is better suited.



Frank - that is interesting: I did not know about the online viewing of in-game help files. Is there a way to do this separately for Simutrans-Extended's help files at present? If not, it would be helpful if that could exist.

For this, it only needs registered data.

Offline zook2

  • *
  • Posts: 321
Re: SimEx documentation / wiki
« Reply #10 on: December 02, 2017, 05:00:11 AM »
I did some pages a while ago about signals and how to use them. I even have a page under construction, still only on my computer, which would give some concrete examples of in which situations to use what signals.
Feel free to use any of those pages, and you could even split them up into smaller pages. Some of them are lacking information (ie, on absolute block, I think).

Can you PM them to me? Also it would be quite useful to know which type of signals become available in which year (in pak.britain.ex). I guess I could find out myself, but I don't even know where to begin.

Offline Ves

  • Devotee
  • *
  • Posts: 1664
  • Languages: EN, SV, DK
Re: SimEx documentation / wiki
« Reply #11 on: December 02, 2017, 10:21:32 AM »
I’m away from home this weekend, so I can’t pm you. You can, however, find them in the text/•somethingsomething• where all the help texts are located. My pages have “signal” in the beginning of the name and there are around four pages, so they should be easy to locate.

Incidentally, it’s a very good idea to have a wiki about the signals them self’s in pak Britain. That’s a limitation in the help pages that you can’t have pakset specific pages.
Maybe you could get James to describe some details of British signaling?
Otherwise, just work your way one by one in the signals.dat, located in the pak Britain repository on GitHub.

Offline zook2

  • *
  • Posts: 321
Re: SimEx documentation / wiki
« Reply #12 on: December 04, 2017, 06:29:52 PM »
The wiki is slowly taking shape:

https://simutrans-germany.com/wiki/wiki/tiki-index.php?page_ref_id=1767

However, I'm not happy at all with the signalling documentation. I have played Simutrans for ages, but I'm an absolute beginner when it comes to the new system. And while I've learned a few things putting together the wiki pages about signals, I'm not sure how other beginners might feel about it. Actually, I wonder how you all have learned to master it. Trial and error? Did they teach railway signalling in school and I missed it?

Anyway, I'm trying to write something that both explains the basics to a newbie, and can serve as a handbook for more experienced players.

- First I'd need a better introduction to the whole thing. Evolution of signalling, signal types, how and when they were used etc.. Most of the information you'd need is there in the wiki now, but it's still a bit of a mess. What I'd like is some kind of take-me-by-the-hand tutorial, from which I could link to the relevant pages containing the gritty details. Also, are there any more sources of information where the gritty details are explained? For example, in one of the videos James explains the 7-tile (825m) sight distance for determining signal status, and that the train slows down if the signal is not yet in sight. This isn't explained anywhere else. I'm sure I'm missing more things.

- Second, I might build a tutorial scenario showing simple examples of all signalling methods and signal types. I thought I could just start a new map with the timeline off, but apparently I don't get to use all the signals then. Or do I? Does anyone already have a map I could use, a test bed for coding purposes perhaps?

- Finally, some beginner's questions:

What's the difference between signalbox "radius", and "max_distance_to_signalbox" for signals? Sholdn't they be the same?

What happens if I build more signals inside the radius than the box can control?

"searchlight signalling" is in the list of types, but not used?

Do trams use the same signals as railroads? Any differences?

OK, the year is 1840 and I have at my disposal: a Vane Signal, a Vane Auxilliary Signal, a Vane Station Signal, plus Vane Choose/End Choose signals. All very fine, except I don't know what some of them they do. Does Auxilliary Signal mean Presignal? What's a Station Signal? It's not mentioned anywhere.

Offline Ves

  • Devotee
  • *
  • Posts: 1664
  • Languages: EN, SV, DK
Re: SimEx documentation / wiki
« Reply #13 on: December 04, 2017, 07:17:51 PM »
Looking good!  :thumbsup:

Hehe, I understand it is an advanced topic! I myself learnt it in paralell when James programed it. Since I have my own pakset (or at least the scrambling fundaments of it) I made the signals of it together with the new features.

To take them in order:

Quote
Anyway, I'm trying to write something that both explains the basics to a newbie, and can serve as a handbook for more experienced players.

- First I'd need a better introduction to the whole thing. Evolution of signalling, signal types, how and when they were used etc.. Most of the information you'd need is there in the wiki now, but it's still a bit of a mess. What I'd like is some kind of take-me-by-the-hand tutorial, from which I could link to the relevant pages containing the gritty details. Also, are there any more sources of information where the gritty details are explained? For example, in one of the videos James explains the 7-tile (825m) sight distance for determining signal status, and that the train slows down if the signal is not yet in sight. This isn't explained anywhere else. I'm sure I'm missing more things.
I think I wrote it somewhere in the help texts back then in conjunction with presignals, but I might remember wrong. But that is true, a signal can only be seen from within a certain distance and will slow down if it needs to. Be aware though, that it maybe is possible to change the sighting distance in simuconf, why it would not be so good to hardwrite the distance in the wiki.
Also, bridges, tunnel entrances and corners will shorten the sighting distance

Quote
- Second, I might build a tutorial scenario showing simple examples of all signalling methods and signal types. I thought I could just start a new map with the timeline off, but apparently I don't get to use all the signals then. Or do I? Does anyone already have a map I could use, a test bed for coding purposes perhaps?
Well, you should certainly have all signals at the same time then, not?

Quote
- Finally, some beginner's questions:

What's the difference between signalbox "radius", and "max_distance_to_signalbox" for signals? Sholdn't they be the same?
Signalbox radius:
The max distance that the signalbox can controll signals. Say an old mechanical signalbox, where you due to the technique of the signalbox can control signals within the nearest 500 meter.

max_distance_to_signalbox:
The max distance that this signal can be put from a signalbox. If it is controlled by wire, the maximum distance for connecting with wire might be 2000 meters.

Later on, if you then get an electro-mechanical signalbox which is technically stronger, this new signalbox might have a radius of 2000 meters, and so can use the same kinds of signals as the old signalbox.

Note that for moving block working method, the max_distance_to_signalbox parameter is fundamentally different:
Since it is intended to simulate modern era signals which can communicate with each other, the setting now dictates the max distance between the signals instead of to the signalbox. It works like this:
First signal must be connected to the signalbox and within the radius-limit of the signalbox, but the rest of the signals you build can be much further away from the signalbox, as long as they are within the above mentioned range.

Btw, did you read the "Dat file reference for: Signals and Signalboxes" -thread? https://forum.simutrans.com/index.php?topic=14848.0
This explains some of these parameters.

Quote
What happens if I build more signals inside the radius than the box can control?
Nothing, since it is wether they are connected to that signalbox that is important. To connect a signal to a signalbox, simply open the signalbox info window before placing signals. When the signalbox is "full" a message will occur, telling that no more can be connected.

Quote
"searchlight signalling" is in the list of types, but not used?
What!? Never heard of that. Where did you find it?

Quote
Do trams use the same signals as railroads? Any differences?
Yes, exactly the same. All rail waytypes works in this way now.

Quote
OK, the year is 1840 and I have at my disposal: a Vane Signal, a Vane Auxilliary Signal, a Vane Station Signal, plus Vane Choose/End Choose signals. All very fine, except I don't know what some of them they do. Does Auxilliary Signal mean Presignal? What's a Station Signal? It's not mentioned anywhere.
A Vane signal is confusing due to no one knows what a Vane signal is outside GB (me included, until I read upon it)  ;)
It is just called a "vane signal", but is in fact only a signal which in Simutrans uses the time interval working method.

Auxilliary signal I actually dont know without seing it in game.

A tip to find out what a signal "is", is that you can build it and open its info window. There you will find some entries which would give you a hint of what it is.

A station signal is, well a bit confusing! One single station signal is intended to control an entire station, that is all platforms in all directions. What it does is that it releases trains correctly, and even creates a directional reservations, but I dont remember from on top of my head in which configuration it does that. There only exists three possible station signals:
- Time interval Station signal
- Time interval with telegraph Station signal, and
- Absolute block Station signal
.. where pakbritain only uses the two time interval working methods. Paksweden will use all three of them.

Some of this info is available in the "Dat file reference for: Signals and Signalboxes", under the "is_longblocksignal" section.


I do have some games with signalling if you are interrested. Additionally, I had played around some graphics which should illustrate the different working methods in the game, how to place the signals and what reservation types they create. If you are interrested to have a look, I can also send those.

Offline Vladki cz

  • Devotee
  • *
  • Posts: 2676
    • My addons, mostly roadsigns
  • Languages: EN, CS
Re: SimEx documentation / wiki
« Reply #14 on: December 05, 2017, 09:44:53 PM »
Perhaps there are some confusing things for beginners. You won't see any (or just a few) signals in the rail toolbar, unless you build a signalbox. When you click on a signalbox, the toolbar will extend and show available signals.

signalbox to signal distances: Lets' have an imaginary electro-machanical signalbox, that can control both mechanical semaphores, and electric light signals. It can control signals within 10 km radius (i.e. a big station and a nearby junction, loop or siding). But semaphores usually have max_distance_to_signalbox at 1-2 km. Electric light signals may have unlimited max_distance_to_signalbox. There may be another more modern big central signalbox, that can control signals in 100 km radius.
When building signals, both values are checked and the lower of them is used.

Names of signals mostly refer to their appearance - vane, semaphore, searchlight, and do not tell anything about how they work. Look at the hint bubble when pointing on them, and look at working method. That is important. The description of working methods is covered here: https://forum.simutrans.com/index.php?topic=14848.0

Sighting distance and distant signals/pre-signals (maybe the auxiliary signal is a distant signal). If the sighting distance is shorter than breaking distance, the train will start breaking well ahead of signal in order to stop at it. It may start accelerating again only if it gets within sighting distance of signal (and the signal is clear). To avoid this, you have to build a distant signal at the breaking distance (or further) from main signal. In modern era, you can use multi aspect signals to combine a distant and main signal in one - that allows you to make the blocks shorter. With 3-aspects the block should be equal to breaking distance (you can see that in depot as it will vary for each train). 4-aspects allow you to make blocks at half of breaking distance.

Simple signals work similar to standard, but single faced signals can be passed in the opposite direction. You need to use on-way signs to force a single directional track.

Choose signals work similar to standard, but can show a special aspect if train goes to alternative platform.

Long signals were replaced by token-block and one-train-staff working methods.

And last but not least - knowing how real world railway signalling works helps a lot. The aim was to make simutrans singalling as close as possible to real world.

Offline Frank

  • Inactive/Retired
  • *
  • Posts: 1431
  • Languages: DE
Re: SimEx documentation / wiki
« Reply #15 on: December 17, 2017, 08:54:50 PM »
Frank - that is interesting: I did not know about the online viewing of in-game help files. Is there a way to do this separately for Simutrans-Extended's help files at present? If not, it would be helpful if that could exist.

https://www.simutrans-germany.com/translator/data/htmlex/en/index.html

I importet way_wear.txt from SVN and fixed p-Tags

Offline jamespetts gb

  • Simutrans-Extended project coordinator
  • Moderator
  • *
  • Posts: 18690
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: SimEx documentation / wiki
« Reply #16 on: December 17, 2017, 08:59:32 PM »
That is very useful - thank you. How can we add the other help files for Extended to this page/system?

Offline zook2

  • *
  • Posts: 321
Re: SimEx documentation / wiki
« Reply #17 on: December 17, 2017, 09:10:02 PM »
How can we add the other help files for Extended to this page/system?

I've used a free text editor called Notetab Plus. It has a function to strip HTML tags (Tools/Open Clipbook/Convert HTML to Text). Done in a second.

Offline Frank

  • Inactive/Retired
  • *
  • Posts: 1431
  • Languages: DE
Re: SimEx documentation / wiki
« Reply #18 on: December 17, 2017, 09:48:33 PM »
write a file for object import

Code: [Select]
obj=help_file
name=filename
note=

then copy the text into the translation page

example import file attached

syntax for help texts

I've used a free text editor called Notetab Plus. It has a function to strip HTML tags (Tools/Open Clipbook/Convert HTML to Text). Done in a second.

The error was <p> and </p> in the wrong order.

Offline jamespetts gb

  • Simutrans-Extended project coordinator
  • Moderator
  • *
  • Posts: 18690
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: SimEx documentation / wiki
« Reply #19 on: December 17, 2017, 10:15:14 PM »
Excellent, thank you.

Offline Frank

  • Inactive/Retired
  • *
  • Posts: 1431
  • Languages: DE
Re: SimEx documentation / wiki
« Reply #20 on: December 23, 2017, 07:49:46 AM »
I importet help file list from svn /text/en in to the Translator

not set note field

Offline jamespetts gb

  • Simutrans-Extended project coordinator
  • Moderator
  • *
  • Posts: 18690
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: SimEx documentation / wiki
« Reply #21 on: December 23, 2017, 12:13:39 PM »
I importet help file list from svn /text/en in to the Translator

Thank you.

Offline Frank

  • Inactive/Retired
  • *
  • Posts: 1431
  • Languages: DE
Re: SimEx documentation / wiki
« Reply #22 on: July 28, 2018, 11:20:53 AM »
I have imported the en help texts in the Translator.
https://www.simutrans-germany.com/translator/data/htmlex/en/index.html

Several tag errors were corrected by me.

With the signals_ * texts, a lot has been formatted with
Code: [Select]
<br> instead of
Code: [Select]
<p> </p>, which makes the texts somewhat confusing.

Especially signals_BACKUP.txt is not formatted in large parts. It is probably assumed that the representation in the game in the text editor corresponds. Although I'm not sure if it is actually used in the game.

Also keys.txt is such a case. For Simutrans standard, the key assignment is taken from the menuconf.tab.

Also the CodeParameters.txt is superfluous because this is documented in the wiki.

And having a file list (all-help-file-names) from version 0.99.00 in the repository/game directory is not very helpful.

And a long time ago I already imported and corrected the way_wear.txt. Even so, there is still the flaw in the game/repository.
I've used a free text editor called Notetab Plus. It has a function to strip HTML tags (Tools/Open Clipbook/Convert HTML to Text). Done in a second.

The error was <p> and </p> in the wrong order.


Offline jamespetts gb

  • Simutrans-Extended project coordinator
  • Moderator
  • *
  • Posts: 18690
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: SimEx documentation / wiki
« Reply #23 on: July 28, 2018, 02:38:26 PM »
Thank you - that is most helpful.