The International Simutrans Forum

 

Author Topic: New help texts for the signallin system  (Read 1047 times)

0 Members and 1 Guest are viewing this topic.

Offline Ves

  • Devotee
  • *
  • Posts: 1820
  • Languages: EN, SV, DK
New help texts for the signallin system
« on: December 27, 2019, 07:08:06 PM »
Hi all, and a Merry christmas to all of you!

I have almost completely rewritten the ingame help texts for the signalling system, making it much more elaborate and added alot of more pages:

signals_overview - Introduction to the signalling system of Simutrans Extended, with small notes on some key features.
signals_help.txt - A FAQ page.
signals_tips.txt - This "Top tips" page contains usefull tips, for instance a "working method upgrade path".
signals_working_methods.txt - Overview page with list of all working methods in the game.

And then a page for each working method with detailed descriptions:
signals_wm_drive_by_sight.txt
signals_wm_one_train_staff.txt
signals_wm_time_interval.txt
signals_wm_time_interval_with_telegraph.txt
signals_wm_token_block.txt
signals_wm_absolute_block.txt
signals_wm_track_circuit_block.txt
signals_wm_cab_signalling.txt
signals_wm_moving_block.txt


All the working method pages mostly come around these topics:
* Main description
* How it works
* Types of signals
* Best uses
* Pittfalls

... where some working methods are fleshed a bit more out than others, due to their complexity, similarities etc.
The help section, and especially the "Top Tip" section could use some more entries from people having useful tips!

You can find the new help texts here:
https://github.com/VictorErik/Simutrans-Experimental-Ves/tree/help-text

Offline jamespetts

  • Simutrans-Extended project coordinator
  • Administrator
  • *
  • Posts: 20805
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: New help texts for the signallin system
« Reply #1 on: December 27, 2019, 08:39:37 PM »
Excellent, thank you very much! Now incorporated.

Merry Christmas!

Offline Ranran

  • Devotee
  • *
  • Posts: 1548
  • Languages: ja
Re: New help texts for the signallin system
« Reply #2 on: December 28, 2019, 01:05:16 AM »
Thank you very much - Ves.

I think it's better to update Simutranslator.
The English text is often up to date with the James repositories, but the Simutranslator remains old.
Due to that inconsistency, some old text update requests have been posted.
« Last Edit: December 28, 2019, 01:17:12 AM by Ranran »

Offline jamespetts

  • Simutrans-Extended project coordinator
  • Administrator
  • *
  • Posts: 20805
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: New help texts for the signallin system
« Reply #3 on: December 28, 2019, 01:28:04 AM »
Ranran makes a good point; Ves - do you have access to Simutranslator?

Offline Ves

  • Devotee
  • *
  • Posts: 1820
  • Languages: EN, SV, DK
Re: New help texts for the signallin system
« Reply #4 on: December 28, 2019, 07:49:19 PM »
Yes, I have acces to the simutranslator, although I need to remember how to use it...

But before I do that, would you mind to read through the pages to see if I have gravely misunderstod anything?

Also, I would like to invite anyone having great tips or some other FAQ questions to post them, so they could be integrated into the help texts!

Offline Matthew

  • Devotee
  • *
  • Posts: 580
    • Japan Railway Journal
  • Languages: EN, some ZH, DE & SQ
Re: New help texts for the signallin system
« Reply #5 on: January 24, 2020, 05:33:11 PM »
Yes, I have acces to the simutranslator, although I need to remember how to use it...

But before I do that, would you mind to read through the pages to see if I have gravely misunderstod anything?

Also, I would like to invite anyone having great tips or some other FAQ questions to post them, so they could be integrated into the help texts!

I have proof-read the first of the signals help text pages. If you think any changes are unhelpful, it is helpful to tell me before I edit more of them.

Offline Ves

  • Devotee
  • *
  • Posts: 1820
  • Languages: EN, SV, DK
Re: New help texts for the signallin system
« Reply #6 on: January 24, 2020, 08:10:24 PM »
Wow, reading your corrected version, I realize how much my english has decaded since school.. I get an "oh, thats right..." all the time, and I also think that your corrections are alot more readfriendly than my original!

One thing:
Code: [Select]
Whenever a train leaves a depot or platform with no signals, it will default to the <a href="signals_wm_drive_by_sight.txt">Drive by Sight</a> working method (with <a href="signals_wm_drive_by_sight.txt">some exceptions</a>).<br>
I dont think there should be two links to the same text page in this way. Players will click on the second link and expect to get served the mentioned exceptions, but instead they get sent to the Drive by Sight page, just as the first link. I also made it a policy not to hide links behind other texts, just so that the player will know for sure what page he is sent to. Whenever a link is called drive by sight, the player knows it is the same page all other drive by sight links go to. A link called some exceptions would add confusion about what page that is, and how the player can get back to it.

Instead I would suggest that we either just remove the link, so it looks like this:
Code: [Select]
Whenever a train leaves a depot or platform with no signals, it will default to the <a href="signals_wm_drive_by_sight.txt">Drive by Sight</a> working method (with some exceptions).<br>... and it is up to the player to realize that he should look at the drive by sight page.
Alternatively it could be rewritten to something like this:
Code: [Select]
By default trains will choose the <a href="signals_wm_drive_by_sight.txt">Drive by Sight</a> working method when leaving the depot or a platform. There are some exceptions to this rule, which can be read more about on the drive by sight page.<br>
What do you think about that?

The exceptions are actually not mentioned directly in the Drive by Sight page, only indirect. There is a point about the default working method, and a mention about the exception-responsible working methods and their pages are linked. Do you think we should mention it specifically in this page?


However, other than that, it looks very good! :thumbsup:

Offline Ranran

  • Devotee
  • *
  • Posts: 1548
  • Languages: ja
Re: New help texts for the signallin system
« Reply #7 on: January 24, 2020, 10:24:58 PM »
I think that the explanation of each working method is easy to move if the link list is at the top like this.

Code: [Select]
<a href="signals_working_methods.txt">Signals working methods</a> > Cab signalling<br>

<a href="signals_wm_drive_by_sight.txt">Drive by sight</a> |
<a href="signals_wm_one_train_staff.txt">One train staff</a> |
<a href="signals_wm_time_interval.txt">Time interval</a> |
<a href="signals_wm_time_interval_with_telegraph.txt">Time interval with telegraph</a><br><a href="signals_wm_absolute_block.txt">Absolute block</a> |
Cab signalling |
<a href="signals_wm_moving_block.txt">Moving block</a> |
<a href="signals_wm_track_circuit_block.txt">Track circuit block</a> |
<a href="signals_wm_token_block.txt">Token block</a><br>

Well this is a design that is often found on websites. However, the problem is that there is no fixed minimum width or scroll bar in the x direction, so the layout collapses when the window size changes. (´・ω・`)


Currently, the minimum size of the help window is not set, but it is very difficult to read it if it is made small, so it is better to limit the minimum size.
Message centers and popup messages also have a reasonable minimum width.

Offline Ves

  • Devotee
  • *
  • Posts: 1820
  • Languages: EN, SV, DK
Re: New help texts for the signallin system
« Reply #8 on: January 24, 2020, 11:31:34 PM »
That does look pretty good actually. I had wondered how to best do the different working method pages, as I found it too much to list all the working methods directly in the left hand page list, hence the birth of the "Signals working methods" page. But this is brilliant, and makes you able to consistent switch between all working method pages without having to go through the previous "Signals working methods" page. However, the order should always be the same, and the same as they are in the original working method list:

Code: [Select]
<a href="signals_wm_drive_by_sight.txt">Drive by sight</a> |
<a href="signals_wm_one_train_staff.txt">One train staff</a> |
<a href="signals_wm_time_interval.txt">Time interval</a> |
<a href="signals_wm_time_interval_with_telegraph.txt">Time interval with telegraph</a> |
<a href="signals_wm_token_block.txt">Token block</a> |
<a href="signals_wm_absolute_block.txt">Absolute block</a> |
<a href="signals_wm_track_circuit_block.txt">Track circuit block</a> |
<a href="signals_wm_cab_signalling.txt">Cab signalling</a> |
<a href="signals_wm_moving_block.txt">Moving block</a>

May I ask, do you mind the resizing issues that Ranran points out?



On another note, Matthew did you write in the other thread that you found the help files on simutranslator? Are you sure, because I cant find them there... :o

Offline jamespetts

  • Simutrans-Extended project coordinator
  • Administrator
  • *
  • Posts: 20805
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: New help texts for the signallin system
« Reply #9 on: January 25, 2020, 10:13:05 PM »
Thank you all for your work on this. I have not had the chance to review this in detail, so will trust that you are all writing sensible things. Ranran's suggestion for the organisation of the working methods is good - thank you for that.

Offline Ranran

  • Devotee
  • *
  • Posts: 1548
  • Languages: ja
[patch]Extend minimum width of the help window
« Reply #10 on: January 25, 2020, 10:28:52 PM »
Currently, the help dialog window size can be reduced like this.

I don't think it makes sense to be able to be so small (displaying only the menu bar).
If you temporarily feel that the help dialog is in the way, you can right-click the help dialog's title bar.

I made a patch to expand the minimum width and threw a pull request
https://github.com/jamespetts/simutrans-extended/pull/134

I believe this will help layout the link list at the top of the page which I suggested.

Offline jamespetts

  • Simutrans-Extended project coordinator
  • Administrator
  • *
  • Posts: 20805
  • Cake baker
    • Bridgewater-Brunel
  • Languages: EN
Re: New help texts for the signallin system
« Reply #11 on: January 26, 2020, 01:17:00 AM »
Incorporated - thank you.