In-game help texts out-of-date

[sanna]

First: I am very unsure which is the best place for this. In Documentation and Resources? In Extension requests? I Development and bugs? It concerns documentation, but in-game documentation rather than external documentation; it concerns deficiencies in-game - which could be considered a bug; it concerns possible enhancements to facilitate things which is clearly an extension request... Moderators, please place this where you think is most appropriate...

Sorry to open a can of worms, but.... I know it is really too late for the fast upcoming new stable release, but a quick look at the help texts at SimuTranslator showed some glaring omissions from the help texts. I could for example (in the languages I can read) not find a single mention of the possibility to build ways by dragging; the underground help text is not available in English (I will try to give it a go - but it would be better if a native English speaker looked it over - and perhaps a native German speaker to make sure I understood the German text correctly *smile*). I am sure there are others. That is, the things we want to highlight for the upcoming release (the new stuff...) is not documented in help. If it is and I have missed it, no one would be more relieved than me.

This has spawned a lot of thoughts about how to keep the help texts up-to-date with current version. The help texts today are long and unwieldy (for the translator I mean). It is hard to keep track of changes in the German texts (which mostly are the most up-to-date versions), and in several cases I have refrained from translating the help text because I know that then the Swedish language users will miss information that is present in f ex German or English (I will not be able to keep up...). First of all it would be very nice if SimuTranslator could show _when_ (and not only by whom) a given text was last updated; this would help translators determine if their language version needs checking or not.

I think that we need to split up the help texts into shorter paragraphs, and that the help text pages need to be a composition of these paragraphs, and allow for fallback to English/German for missing paragraphs as well. Yes it will mean mixed languages on a single page, but it will also mean that all users regardless of language will get most information, still only most, since changes within a single paragraph still will not be reflected. I also think we need to specify one and one only language that is "master", and IMO the obvious choices here are German (which often is most up-to-date) or English (that probably is the most widely understood). German can IMO only be chosen if we have someone who is dedicated to transfer any changes in the German text to the English counterpart, since most other translators will work from the English text.  I must confess that I am not totally convinced that SimuTranslator is the best tool for translating specifically help texts; some sort of gettext fuzzy-marking would be very nice to have here - which of course is not possible unless we have a "master" to compare to.

The way the keyboard shortcuts have been handled is an excellent example of how things could be simplified for the translator. It would be very nice if something similar could be used for other help texts; I am referring to the currently manual synchronization the translator has to do between f ex the button text within a specific dialogue, and the help text referring to the same button.

There are also many existing paragraphs that are nearly identical (and should be so) in several help texts; f ex the paragraphs on how to build a stretch of railroad/road/tramway etc only differ in the reference to the way type - and this is a good thing, you build them in the same way, the texts should be identical. Again, the syncing of these paragraphs is a manual task for each translator team. If it was possible to rewrite these paragraphs in a more general wording so that they did not specifically mention the way type, then they could be reused on each and every help text about building ways.

Maybe these suggestions are too early, maybe Simutrans is not "mature" enough to have good in-game help texts. Maybe our developers still need to focus on more game central things than help texts... For while the actual production/translation of help texts is something we all can help out with, the changes to the code that are needed is a different story..

[Dwachs]

Some suggestions from my side. Imho the following things can be implemented without to much effort:

(1) Make helptexts available for each tool (now only toolbars and windows can have helpfiles). This would make it possible to split large help texts into small pieces

(2) Make it possible to include another help file with a new tag <include src="otherfile.txt" />. This then will become handy if one can compose the helpfile for a toolbar from all the single helpfiles for the individual tools.

(3) An addtional translate tag: <translate>text to be translated to whatever language</translate>, where one can refer to already translated pieces of text.

[vilvoh]

The second point is already implemented. I like the idea of splitting the translated texts, as many of them are very long and it's quite annoying to translate them.

[Dwachs]

The second point is already implemented.

Really? I did not meant links <a href="... but the possibility to include (or embed) the other text in the current text.

[prissi]

One could make use of the full features of hypertext and make additional files, for instanc eon "How to built tracks" and just give a link like "how_built_track.txt" Automatic reuse is impossible, imho, since languages are too different for that. Just thinking of automating "die Startbahn/das Rollfeld/ der Stop" brings me Nightmares. I would not embed text, since those helptexts are already quite long. Let people surf around seems more useful to me. (And that inevietely triggers the question of a search engine.)

Since the help files are HTMLish anyway, I thing a site with them as online reference (with additiona img tags, which I can teach the program to ignore) might be a good addition to inspire more editing of help text. Or even just reformat them and put them it the wiki would work.

Tthe only one who looks after those texts in English was Timothy two years ago and me. This is one of the things I actually do for german before releasing a stable. But honestly, I have to do everything, and that is work not fun. Thus I do stable seldomly.

For english only 58% of the texts are translated for pak64 at all! Clearly, despite having one of the largest communities by CAN/AUS/GB/US people no one loves Simutrans enough to translate text or to improve error messages and so on. Or they are atisfied with the short english placeholders. That is imho the main problem (albeit it slowly improves.)

[sanna]

One could make use of the full features of hypertext and make additional files, for instanc eon "How to built tracks" and just give a link like "how_built_track.txt" Automatic reuse is impossible, imho, since languages are too different for that. Just thinking of automating "die Startbahn/das Rollfeld/ der Stop" brings me Nightmares. I would not embed text, since those helptexts are already quite long. Let people surf around seems more useful to me. (And that inevietely triggers the question of a search engine.)

Automatic reuse of single words/phrases if of course out of the question, but would it really be impossible to include the content of a separate file in place rather than "simply" adding a link? Something similar to a server side include....

Since the help files are HTMLish anyway, I thing a site with them as online reference (with additiona img tags, which I can teach the program to ignore) might be a good addition to inspire more editing of help text. Or even just reformat them and put them it the wiki would work.

This sounds as a very good idea, at least if the wiki in question supports easy translation into other languages. Maybe Frank has place for it on the German wiki?

[IgorEliezer]

Isn't HTML "readable" in every OS? Why not to create a HTML manual distributable along with Simutrans download?

I downloaded games and softwares (e.g. Blender) which their manuals are in HTML and are included along with download package - so I don't need to access a WebSite to read them.

My idea:
- create a "manual" folder where HTML files and images are stored per language.
- a shortcut in Simutrans folder pointing to an index.html where the user can choose the language.
- in-game help would be shortened.
- Manual's images could be generic and with no text so they could be used in any language.

[prissi]

The simutrans help texts could be displayed in any browser as they are. Only the ending needs to be htm ... but this can be done via automatic renaming. Chanhing the simutrans file name from txt to htm is a piece of cake. Calling a brower - plattform independent - is unfourtunately still some of the unsolved stuff in cross plattform development.