New Help files

[Ves]

I started the process of updating the help files with some of the new (and some old too) features of Simutrans Ex.

The files can be found at the Github repository here: https://github.com/VictorErik/English-help-files
In order to make them work properly, the game must be recompiled using the file in the /gui/help_frame.cc

I have the feeling that the help section is a little random at the moment with many "addons" over the time. Are there any whishes or recommendation as to how the help section in general should be structured?

I have also no knowledge of how the translations work. Can anybody tell me what am I to look at/worry about when creating new files?

Anyway, I have currently created only one file, that is:
way_wear.txt and handles (I think) everything the player needs to know about way wear.

[Frank]

I think I can include experimental help files in Translator

[jamespetts]

Viktor - thank you very much for that: I have merged your new files. That is most helpful: work on documentation is very welcome indeed. Your modified help_frame.cc is now incorporated into devel-new, so there is no need to compile a special version.

Frank - it would be helpful indeed if you could include the Experimental help files in the translator: thank you.

[Frank]

set Sim-Exp help file create

Maintainter: jamespetts

import

obj=help_file
name=file name
note=description for Note field
--

for export I change the php-files in the next days

question

Export include the standard help files ( missing in Experimental ) or not?

[Ves]

I think I can include experimental help files in Translator

Great, what do I doo to make that easier for you?

Viktor - thank you very much for that: I have merged your new files. That is most helpful: work on documentation is very welcome indeed. Your modified help_frame.cc is now incorporated into devel-new, so there is no need to compile a special version.

Thank you! Well, there will come a new help_frame.cc for every document that is written, so it will change again!

Incidentally, what do you think of the content? the layout?
I was thinking having this division in the files, so one easy can get an overview.

Next subjects to touch?
Signals?

[Frank]

way_wear.txt is importet

export I think works

not include standard help files

not save as html files for browser

[Ves]

Ok, by

not include standard help files

You mean I should only upload files specifically for simutrans Ex? The files on my github branch is the entire help section for the english files containing a mix of standard files and experimental, some correct some incorrect. My plan was to add/modify textfiles in commits, but is it better if I remove all "unfinished" files from the github?

not save as html files for browser

Im sorry I dont understand I save the files as .txt, but maybe this is not what you meant?

[Frank]

the export of the program texts takes everything from standard to which it is not at experimental are (objects in Translator)

this is not for the help files ( requiring additional changes to the php files )



the Translator save the help files in a directory as html
thereby one has a better overview when you edit the help

this is not for experimental ( requiring additional changes to the php files )

but they can not accept texts via text comparison for same object name
see here

[jamespetts]

We probably need separate versions of the help files for Experimental because they will be different from Standard in many ways, but we probably need to start with copies of the versions from Standard and slowly adapt them. Some of the help files already have Experimental specific content.

[Ves]

I thought about doing signals next as it feels as an area which are mostly finished (and an area that I mostly understand! :p ).
However, it's a big subject in sim ex, and would need some very organized and proper documentation so players understand. From on top of my head maybe something like the following:
Signals_overview (brief how signals works)
Signals_multi_aspects (describes the aspects and how to place them)
Signals_working_methods (maybe a page per working method, although then it's becoming huge...)
Signals_signal-boxes (because there must be some info on how to use them)
Signals_special (containing info about eg choose signal, permissive signals etc)

What would you (or anyone else) suggest?

On top of this, did you get to work on showing the working method in the signal info window?

[jamespetts]

One question here before considering this more fully: what do you mean by "aspects" here? Normally in signalling, an "aspect" is a particular state of a signal (clear, danger, etc.), but you refer to "placing them" as if you are referring to entire signals. Can you clarify?

[Ves]

Well, it was merely from on top of my head. I meant multi aspects as in "multi aspect signals", and I was thinking something like these topics under such a headline:

* All possible aspects existing, what they mean and with which working methods they work.

* Where to position signals in relation to each other (eg presignal BEFORE the main signal, etc)

Although Im in no way sure the best way is to group those two together. However, I think both subjects needs to be explained.

edit: Maybe a better headline for the two would be:
Signals_aspects_and_placement ?

[Rollmaterial]

I think a more correct English word would be "usage".

[jamespetts]

A better way of organising this is likely to be:

(1) an overview of signalling in Simutrans-Experimental generally (the need for signalboxes, defaulting to drive by sight without signals, etc.);
(2) an overview of how each type of signalling (working method) works*; and
(3) details of the more advanced aspects of each type of working method, including a full description of each type of signal and its various aspects **.


* Note that time interval is still under development and one train staff needs fixing.
** Note also that there may be some changes here in future, in particular, the "call on" aspect is planned to work with convoy re-combination (e.g., multiple units joining together, a locomotive backing onto carriages) as well as with permissive block signals.

[Ves]

That is probably a good way to do it! I already started writing descriptions of working methods and some other text and will rearrange it to fit under those headlines. However, it has to wait a little as I'm away some days.
Regarding the description of types of signals, I would like to describe them in general and not referring to the specific ones in pak.britain-Ex if that's ok with you. Therefore a more generic description would be needed and a pressure on pakset maintainers to properly name their signals.

Each subject below would include information about all of the available signal states, and wether some signals only work in some working method (eg the moving block signals). Also I imagined a short description of where to place them.

Normal signals (red-green)
Presignals (with clarification about absolute block)
Three- or more aspect signals (with clarification about "combined signal" and "time interval signals")
Moving block signals
Choose signals
Permissive signals

What about signs? Should they get a page of their own or joined together with eg signal details page?

[jamespetts]

Yes, this seems sensible. As for generic descriptions, this is a good idea, but you might want also to include the names of the specific signals in known Experimental paksets as well, for example, under the heading "pre-signal", add somewhere in the text, "This is a 'distant signal' in Pak128.Britain-Ex", and so forth. As to "normal signal", I believe that "stop signal" is the more correct generic terminology, is it not?

As to signs, it would seem sensible if they could be separate from signals, as they work slightly differently (not having states).

[Ves]

I could agree on having some examples from the British pakset.

"Normal signals" versus "stop signals", I always tend to think that ALL signals (except presignals) are stop signals but this might also be an English term?

However, regarding the pakset examples made me think of having automatically individual help files for each pakset? When pak Britain is loaded, it loads the usual help files, then a link (in the signals page) to specific pak Britain help files. This would although require a code change so the Swedish or czheck pakset would load their respective help files instead. This could eventually be extended so a pakset could have pakset descriptions for vehicles, infrastructure etc....
Would you consider this? If yes, I could start doing a page with description of ALL pak Britain signals and just put a link somewhere in the signals page.

[jamespetts]

Ahh, I see what you mean - perhaps "basic" signals? There is nothing abnormal, per se, about, say, a junction (choose) signal.

This is an interesting idea (the pakset specific help files). It would be a very long way down the queue of tasks, however, which is very long. I wonder whether this might be something to suggest to the Standard developers, as I am sure that there might be an advantage to having pakset specific help files there, too.

[Ves]

"basic signal" is a good compromize!

One could write the pakset files (it really just is one file at the moment which anyway will take long time to write) and link it to some of the signal pages and then when/if eventually pakset specific helpfiles gets included, one could use those files.

Only questions about that file (that will become something like "pak128.britain-Ex_Signs_and_Signals"):
What to describe and in which order?
Timeline order? Order by working method?

Descriptions:
Number of states and what the signal will look like for each state.
Working method
Compatible Signal boxes
Other info.....

[jamespetts]

Because some signals (e.g. choose signals) are the same in different working methods, one should describe the individual signals separately from working methods, perhaps chronologically.

[Ves]

huh, writing and writing and it becomes a bit tricky.. Suddenly, I found myself trying to in detail describe where exactly its best to place normal stopsignals of various working methods, but thats EXTREMELY difficult to write in words as well as it becomes a HUGE amount of text! I have to limit myself somehow.....
I have updated the Github, creating the desired pages inclusive a "signs" page. The status are as following:

signals_overview.txt:  Almost finish
signals_usage.txt: Overall finish? Far from complete, lots of information wanting to be on the same page. Any suggestions as how to break it down or streamline it, alternatively splitting up in more pages? Currently it feels too spread and uninformative I think...
signals_working_methods.txt: almost finish
signals_signs.txt: finish

edit: I have worked more on the "usage" and I think it got a bit better. Would anyone like to look at it to see what spots I have missed and if I have made it clear enough?

[jamespetts]

Apologies for not having responded sooner; I have been rather busy. I will look at this when I get a chance. Thank you very much for your help.

[jamespetts]

Looking at this, t he new help files do not appear to be linked from anywhere. The place to link them from would be the current "Railway tools" help file, which contains out of date information about signalling (and other things) and is written in somewhat broken English. May I suggest that you update this file to integrate your new files into the main help system?

Edit: Actually, I think that there may be another problem here: the new help files do not appear in the game, the old help files being used instead. This appears to be because the files are in the root directory of the Github repository rather than in the /text/en directory. Using it as things stand would require manually moving the files every time that they were updated, which is impractical. Do you think that you could reorganise your Github repository to have the files in the right place? I should be very grateful.

[Frank]

...
Edit: Actually, I think that there may be another problem here: the new help files do not appear in the game, the old help files being used instead. This appears to be because the files are in the root directory of the Github repository rather than in the /text/en directory. Using it as things stand would require manually moving the files every time that they were updated, which is impractical. Do you think that you could reorganise your Github repository to have the files in the right place? I should be very grateful.

I think it should be used directly in the Translator.

It can 2 CoMaintainter be appointed for the object import.

This would also translate the Timely allow.

[jamespetts]

The files can be both on Simutranslator and Github at once, can they not? That may be the better solution, although Simutranslator does not (to my knowledge) have the sort of automatic versioning that Github has, so it may be better to add them to Simutranslator once they are reasonably finalised rather than add them manually many times over for each edit.

[Ves]

Currently it was only the text written text (and the internal linking of the signals helpfiles) that I meant to get feedback on. Later, the relevant pages would be linked from:
Rail tools (including all rail that uses the system)
A wish to make it link able from the signals themself  as well as from the signal boxes themself.  (I could maybe give that a try myself)

Regarding the placements of the files on github, do you mean the it would e easier for you if the files where having the path: /text/en ?
Reason they are where they are is because I made a repository directly inside your experimental repository however, I can try to change it later.

[jamespetts]

Currently it was only the text written text (and the internal linking of the signals helpfiles) that I meant to get feedback on. Later, the relevant pages would be linked from:
Rail tools (including all rail that uses the system)
A wish to make it link able from the signals themself  as well as from the signal boxes themself.  (I could maybe give that a try myself)

The reason that I commented on this first was because I tried to access the help files from within the game, so that I could see them as they are actually presented to users, and was unable to find them.

Regarding the placements of the files on github, do you mean the it would e easier for you if the files where having the path: /text/en ?
Reason they are where they are is because I made a repository directly inside your experimental repository however, I can try to change it later.

Yes, that is indeed what I mean - it would be very helpful if you could change this, as it would make maintaining the help files very much easier. You can also then modify multiple language help files and interact with Simutranslator rather better.

[Ves]

The reason that I commented on this first was because I tried to access the help files from within the game, so that I could see them as they are actually presented to users, and was unable to find them.

Did you compile with the new help_frame.cc? Currently, they should all be available at the index of the help section.

Yes, that is indeed what I mean - it would be very helpful if you could change this, as it would make maintaining the help files very much easier. You can also then modify multiple language help files and interact with Simutranslator rather better.

Ok, will mixture with it!

edit:
Now I have altered the position of the files, so they are in text/en/. Also, I have prepared the other languages (on my desktop) via ".gitignore" so they easy can be uploaded.
The file "help_frame.cc" is still located in gui/ Is there a better place to have it do you think?

[Ves]

I have almost entirely rewritten the railtools.txt as it was quite outdated on some points, and also it was weird to describe some new things in more detail when other things almost where not described at all. The signalling (and way wear) help texts are now linked to from that file!
If you think the text is OK, I could continue with the other tool-texts (eg roadtools etc)

[jamespetts]

Thank you for this: apologies that I have been rather busy this week and unable to reply until now. I am afraid that the file locations are still not correct: there were some historical anomalies about the positioning of text files in the repository which I have just spent some time correcting. If you pull from my latest Github commit, you will see the help files in the correct position. This should make updating the help files generally easier in future.

I have also made some amendments to the way wear help file by way of proof reading. One general comment is that it is best to avoid specialised run-together words such as "autorenew" or "halfspeed": it is clearer to spell these out in normal words, as in "automatically renew" and "half speed". (The old help files have been very guilty of this, and I spent a lot of time fixing this a few years ago when I last worked on help files).

I have not had time to look at the other help files yet, but your work on this topic is very much appreciated, as good documentation can make a real difference to the experience of new players.

[Ves]

Thank you for this: apologies that I have been rather busy this week and unable to reply until now. I am afraid that the file locations are still not correct: there were some historical anomalies about the positioning of text files in the repository which I have just spent some time correcting. If you pull from my latest Github commit, you will see the help files in the correct position. This should make updating the help files generally easier in future.

Ok, however, the files appear to be at the same location in your branch as usual? (simutrans/text/en/) or is there something I have missed completely? Is it that you want me to include the "simutrans/" before the text/en/ as well?

I might just remake my repository all the way, creating a branch of your repository instead of making a completely new repository all by my self, as it currently is.

I have also made some amendments to the way wear help file by way of proof reading. One general comment is that it is best to avoid specialised run-together words such as "autorenew" or "halfspeed": it is clearer to spell these out in normal words, as in "automatically renew" and "half speed". (The old help files have been very guilty of this, and I spent a lot of time fixing this a few years ago when I last worked on help files).

Great thanks! Looking at your updates, you have filled in many information holes as well which I have somehow missed!
However, I guess some of the same mistakes (run-together words...) are present in the other texts as well, so I might just proofreading them with that in mind too

[jamespetts]

Ok, however, the files appear to be at the same location in your branch as usual? (simutrans/text/en/) or is there something I have missed completely? Is it that you want me to include the "simutrans/" before the text/en/ as well?

Yes, indeed, the "simutrans/" is important.

I might just remake my repository all the way, creating a branch of your repository instead of making a completely new repository all by my self, as it currently is.

This seems to make sense.

Great thanks! Looking at your updates, you have filled in many information holes as well which I have somehow missed!
However, I guess some of the same mistakes (run-together words...) are present in the other texts as well, so I might just proofreading them with that in mind too

Do! If you produce some new versions as a result, do let me know so that I can look over them. Thank you again very much for your effort.