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

["(Eddie Anderson)" <saywhat@xxxxxxxxxxxx>]

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

"Per I. Mathisen" <per@xxxxxxxxxxx> wrote:
>
>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.

... 


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

   How about a spreadsheet-style interactive help?  It wouldn't
even have to have sentences (hence no need for translations). 

   E.g. the help spreadsheet for food production could have a row
for each of the 32? different terrain types.  The user could scroll
down to the row for the terrain he wanted to know about (e.g.
wheat).  Then the user could add columns for each effect that he
wanted to find out about. 

   There would be 3 sections of columns - the first column, the
last column, and a variable number of columns in between. 

   The first column would have a heading that reads "Unmodified".
The cells under it would show the output of each tile type with no
modifications (e.g. 3 for wheat, 1 for hills, etc.).  This column
would always be on the spreadsheet. 

   The rightmost column on the spreadsheet would be the "Result"
column.  This column would always be on the spreadsheet too.  It's
cells would always be updated to reflect the food output for each
tile type (based on the combined effects of all the non-blank
columns present in the spreadsheet at any given time). 

   In between the "Unmodified" and "Result" columns would be the
columns 2 through ?.  That's where the user could interactively
select the "effects" that he wants help for.  He puts each "effect"
that he wants to see into one the column headings.  Then the effects
of the combination of "effects" are calculated and displayed in the
"Result" column. 


   For example, assume a user wants to know the production of an
irrigated wheat tile under Despotism.  The user would select
"Irrigation" and put that in the heading for column 2.  Then the
user would select "Despotism" and put that in column 3. 

   The rightmost column ("Result") would show the production for
each type of terrain on its corresponding row.  The row for Wheat
would show 3 food at that point. 

   If the user erased the column heading containing "Irrigation",
then the "Result" cell on the wheat row would change to 2.  If the
user had deleted the "Despotism" heading instead, then that "Result"
cell would have changed to 4. 


   The headings could be picked from a menu.  The menu of possible
"effects" would be built from the "effects" list in the relevant
ruleset.  There could also be columns for rivers, roads, mines,
farmland, railroad, distance from the capital, Colossus, King
Richard's Crusade, etc. 

   But tile production is just one part of such a help system.
Just for tile output, there should be at least 3 help spreadsheets -
one for food (as described above) plus two more - one to illustrate
each tile type's trade output and one to illustrate each tile type's
shield output. 

   There should also be help spreadsheets for city output.  There
could be help spreadsheets for city happiness (or unhappiness), city
science, city tax revenue, city food surplus (or deficit), etc.  The
column headings would be things like various buildings (library,
temple, granary, etc.), WoWs, distance from the capital, government
type, etc. 

   And to enhance the usefulness of the spreadsheet, the rows on
those city help spreadsheets would list your own cities on the rows.
Each city's output would be based on whatever tiles were currently
being worked in that city. 

   And there may be a need for other help spreadsheets (to
illustrate other effects).  But I can't think of any other examples
at the moment. 


   I assume that making such a system will be a lot of work.  But
it may solve the problem of documenting the "effects" rules without
requiring translations of text (beyond the headings - which I assume
are already translated elsewhere in the system). 

   Also, if code can be created that will build such a help system
automatically by parsing the ruleset, then it might remove much of
the work of maintaining helptexts (and the translations thereof). 

   What do you think? 


Eddie