[Freeciv-Dev] (PR#15189) Generalized helptext

["Per I. Mathisen" <per@xxxxxxxxxxx>]

<URL: http://bugs.freeciv.org/Ticket/Display.html?id=15189 >

This is an issue I rammed into while working on the advanced governments
patch, but is not dependent on it (meaning this is an issue anyway).

The more the helptext is generalized, the harder it becomes to display it
in a human readable way. Some thinking is needed to come up with a help
system that works well. We may even need to add some hints in the effects
ruleset to help the helptext dialog.

The first problem is where and how to report effects that have multiple
requirements. For example, the police station effect require Democracy,
and therefore shows up there (to my surprise) along with a number of
other effects:

* Allows partisans when cities are taken by the enemy.  Requires the
Communism technology. Requires the Gunpowder technology.
* Each of your cities will avoid 1 unhappiness that would otherwise
be caused by units.  Requires the Courthouse building.
* Each of your cities will avoid unhappiness from the first 2 units
in the field.  Requires the Police Station building.
* Each of your cities will avoid unhappiness from the first 2 units
in the field.  Requires the Women's Suffrage building.

The list gets long this way, and is is not easy to read.

The second problem is generating meaningful sentences for very complex
mechanisms such as the tile penalty. Currently it says:

 * Each worked tile that gives more than 2 Shield will suffer a -1 penalty
when not celebrating.

However, this is not entirely accurate for the Planned government, which
has this penalty for every tile in cities where there is no Factory. (This
is just something I added. Ignore the plausibility of this for now.) Sure,
we can add another sentence explainig that "This applies only to tiles
worked by cities without a Factory building." but see what I said about
readability above.

It gets easier with the new govt patch, since each government has a lot
fewer effects, but for the civ2/current ruleset, the list is awful - too
much and not well written text.

A related problem is that it is not obvious which should be the "key"
phrase in a sentence, nor is it easy to combine effects that are "the
same" effect in human terms but not in the code, as this example shows:

* You gain 75% bonus to Shield production. Requires the Palace
building.
* You gain 75% bonus to Trade production. Requires the Palace
building.

The key phrase here is "The palace building" which does so-and-so, and it
should say "gain 75% bonus to Shield and Trade production" instead of
having two entries. But making proper English sentences here is probably
close to impossible while keeping translations working.

Finally, it gets confusing fast unless ranges are brought in, as in:

* Each worked tile with at least 1 Food will yield 1 additional
Food. Requires the Irrigation terrain special. Requires the Pyramids
building.

(This is not a real example.) Will this give you +1 food in the city with
pyramids or in all cities if you have the pyramids or if any player built
the pyramids? However, adding range seems quite hard without messing up
translations.

Ideas?

I think perhaps we need to "show" requirements and ranges graphically
somehow, but I am not sure how to do that.

 - Per