Split up the helptext field across effects

[Strategy Thinker]

Currently we have something like this (I am using the building aqueduct as an example), in the file cities.ruleset we have the help text

Code: Select all

[building_aqueduct]
name		= _("Aqueduct")
...
helptext	= _("\
Allows a city to grow larger than size 8 and reduces the chance of plague\
 within the city (-30%).  A Sewer System is required for a city to grow larger\
 than size 16.\
")

While in file effect.ruleset we have the effects

Code: Select all

[effect_aqueduct_base]
name    = "Size_Adj"
value   = 8

[effect_aqueduct]
name    = "Size_Adj"
value   = 8
reqs    =
    { "type", "name", "range"
      "Building", "Aqueduct", "City"
    }

[effect_aqueduct_1]
name    = "Health_Pct"
value   = 30
reqs    =
    { "type", "name", "range"
      "Building", "Aqueduct", "City"
    }

This can make it very hard to keep the help text up to date while changing the effects.
What I propose is that the help text can be put directly in the effect file like this:

Code: Select all

[effect_aqueduct_base]
name   = "Size_Adj"
value   = 8
helptexttargets = 
    { "type", "name"
       "Building", "Aqueduct" 
    }
helptext = _("\
Allows a city to grow larger than size 8.\
")

[effect_aqueduct]
name    = "Size_Adj"
value   = 8
reqs    =
    { "type", "name", "range"
      "Building", "Aqueduct", "City"
    }
helptexttargets = 
    { "type", "name"
       "Building", "Aqueduct" 
    }
helptext = _("\
A Sewer System is required for a city to grow larger than size 16.\
")

[effect_aqueduct_1]
name    = "Health_Pct"
value   = 30
reqs    =
    { "type", "name", "range"
      "Building", "Aqueduct", "City"
    }
helptexttargets = 
    { "type", "name"
       "Building", "Aqueduct" 
    }
helptext = _("\
Reduces the chance of plague within the city (-30%).\
")

Also more than one target can be specified to make the help text appear in multiple places.

[ahfretheim]

Yes... I would like to mention an additional advantage of this method, related to the government file: by having custom helptext for government effects in the effects file, we could also avoid unfamiliar government effects not appearing in the government help docs (e.g. AI Love, which is a result of government type in the ruleset I'm working on). Right now, government effects that FreeCiv KNOWS to look for will appear in the help, but even then, aren't always accurate as they won't consider changes in the rules or numbers due to technologies or wonders. Could we maybe enable searching for nreqs as well?

[cazfi]

Works in easy cases, but last time I looked that possibility, complex cases were very bad.
For example multiple effects, but with a bit different other requirement adding practically the same text multiple times ("...provides bonus x under government a...", "...provides bonus x under government b...", "...provides bonus x under government c...") while building helptext could say it in one line listing all the relevant governments.
But we've got some general facilities added since I last considered this, maybe it would be more doable now...

[ahfretheim]

Works in easy cases, but last time I looked that possibility, complex cases were very bad.
For example multiple effects, but with a bit different other requirement adding practically the same text multiple times ("...provides bonus x under government a...", "...provides bonus x under government b...", "...provides bonus x under government c...") while building helptext could say it in one line listing all the relevant governments.
But we've got some general facilities added since I last considered this, maybe it would be more doable now...

Have it appear in the help file for governments a, b & c then. The idea isn't to have a help file for the effects, it is to automatically write the help files for other things using the effects they cause.

[cazfi]

Have it appear in the help file for governments a, b & c then

After which a government may get "...provides bonus x with building a...", "...provides bonus x with building b...", "...provides bonus x with building c..."

Anyway, even if we can't completely switch to the model of documenting everything in effects.ruleset, we could add some additional and optional helptext support there, after which it would be ruleset author's decision which facilities best work in each case.

[ahfretheim]

Have it appear in the help file for governments a, b & c then

After which a government may get "...provides bonus x with building a...", "...provides bonus x with building b...", "...provides bonus x with building c..."

Anyway, even if we can't completely switch to the model of documenting everything in effects.ruleset, we could add some additional and optional helptext support there, after which it would be ruleset author's decision which facilities best work in each case.

If you omit the word "building" it becomes considerably less cumbersome.

[GriffonSpade]

Here's a much better idea: make the help text its own effect entry. Each help text entry will work like a flag description. The help text takes a single type and name, which will be what will load the help text. (Optionally it might take a list, all of which will receive the help text entry)

Code: Select all

[effect_aqueduct_helptext]
name   = "Help_Text"
value   = _("\
Allows a city to grow larger than size 8.\
")
reqs =
    { "type", "name"
       "Building", "Aqueduct"
    }

This will add the line "Allows a city to grow larger than size 8." to the Building Aqueduct's description.