forum.freeciv.org

Posted: **Tue Nov 17, 2015 4:28 am**

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.

Posted: **Tue Nov 17, 2015 1:49 pm**

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?

Posted: **Tue Nov 17, 2015 6:13 pm**

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...

Posted: **Tue Nov 17, 2015 6:30 pm**

cazfi wrote: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.

Posted: **Wed Nov 18, 2015 1:12 am**

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.

Posted: **Wed Nov 18, 2015 1:48 pm**

cazfi wrote:
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.

Posted: **Tue Nov 24, 2015 11:17 am**

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.

forum.freeciv.org

Split up the helptext field across effects

Split up the helptext field across effects

Re: Split up the helptext field across effects

Re: Split up the helptext field across effects

Re: Split up the helptext field across effects

Re: Split up the helptext field across effects

Re: Split up the helptext field across effects

Re: Split up the helptext field across effects