patchFreeciv - Patches: patch #4723, Option to suppress automatic help...

 
 
Show feedback again

patch #4723: Option to suppress automatic help generation from requirements in ruleset ('quiet' attribute)

Submitted by:  Jacob Nevins <jtn>
Submitted on:  Mon 26 May 2014 03:11:57 PM UTC  
 
Category: NonePriority: 5 - Normal
Status: NonePrivacy: Public
Assigned to: NoneOpen/Closed: Open
Planned Release: 

Add a New Comment (Rich MarkupRich Markup):
   

You are not logged in

Please log in, so followups can be emailed to you.

 

Mon 26 May 2014 11:49:28 PM UTC, comment #2:

> I worry that providing a "quiet" flag will encourage ruleset
> authors to embed secret rules, easter eggs, and similar
> constructions.

We've lost that one already -- most of effects.ruleset is not visible anywhere in autogenerated help, nor can it practically be IMO.

I don't think we should treat the ruleset author as an adversary. Rather, we should work with them to make it as easy as possible to produce well-documented rulesets (if that's what they want to do).

> I know I spent a vast number of hours trying to reconcile the
> information in the various help screens prior to learning to
> read rules files directly

Indeed, it turns out that maintaining good documentation for rulesets is hard work. We still occasionally find things in the supplied rulesets which have been there forever but aren't adequately documented, despite years of really quite pedantic scrutiny.

That's a reason I don't want to take on complete automatic representation of all ruleset structures as a goal. Rather, I'd like to focus on good-quality autogenerated documentation of the simple cases that come up 90% of the time, which would be error-prone for ruleset authors, and let them focus on the interesting edge cases.

And as a developer I want the freedom for the canned text to occasionally be inappropriate, so that I can optimise it for the common case; the ability for rulesets to suppress it gives me that freedom.

> "Does not apply to city centers" [...] insert_requirement()
> could presumably accept another argument indicating the thing
> being described, to provide flexibility [...]

Yes, it probably could, but we'll end up adding more extra arguments and plumbing and cases until the code supporting help text generation dwarfs the game engine itself.
See for instance insert_requirement(), where each range of a single requirement type (building) has up to 8 distinct messages (my fault). Most of these will probably never come up, and all of them have to be maintained and translated into multiple languages.

> Failing to tell a player that a Fortress cannot be in
> a city may leave them surprised that it is destroyed
> when the city is built

Indeed; I'm not proposing that. Rather, the ruleset author can write in their blurb "Fortresses cannot be on the same tiles as cities" and suppress the less-obvious "Does not apply to city centers".
(This isn't a great example.)

Jacob Nevins <jtn>
Project Administrator
Mon 26 May 2014 04:09:12 PM UTC, comment #1:

While I agree that the help system is having an increasingly difficult time understanding the requirements structures and describing them well, I worry that providing a "quiet" flag will encourage ruleset authors to embed secret rules, easter eggs, and similar constructions. While these might seem fun at first, they encourage reading raw rules files for distributed rulesets and provide significant familiarity bonuses for undistributed rulesets (or, alternately, encourage hacked clients that download nominally undistributed rulesets from servers).

Patch #3361 seems a reasonable way to help reduce unreadable lists: the (potentially untranslated) property becomes only referenced, and users can check to see the contents of the affected set. Removing the lists may leave the player guessing as to which units can do something (I know I spent a vast number of hours trying to reconcile the information in the various help screens prior to learning to read rules files directly).

"Does not apply to city centers" is just poor text choice, as a result of poor compromises imposed by the textual generation (this particular one being a result of patch #3841): insert_requirement() could presumably accept another argument indicating the thing being described, to provide flexibility in cases where different strings are desired for different sections. Failing to tell a player that a Fortress cannot be in a city may leave them surprised that it is destroyed when the city is built (or not restored if the city is disbanded).

Emmet Hikory <persia>
Project Member
Mon 26 May 2014 03:11:57 PM UTC, original submission:

As we generalise the game engine more and more, autogenerated help struggles to keep up. This is particularly true of help which tries to navigate the requirements system; as we add negation and (maybe one day) disjunctive requirements, and ruleset authors do more complex things with the engine, automatic text generation simply isn't going to able to cope (or at least, produce something humans would want to read).

My approach to this has been to make the help keep quiet about things it can't describe with reliably satisfactory results, and rely on ruleset authors to document anything that's missing in handwritten text.
(In principle, this policy obliges ruleset authors to keep up with the slowly shifting boundary of things the help engine is willing to describe, to avoid duplicates appearing.)

There are also cases where the automatic help generation is technically correct but not ideal. Examples include giant unreadable lists of affected units where the author could have summarised, and the current "Does not apply to city centers" we see in e.g. Fortress help since patch #3826. (We might be able to wordsmith this case, but crafting that text to apply to all situations is hard.)

To help with all this, I propose that requirements gain an attribute 'quiet' (alongside 'present' and 'survives'). If TRUE, this would prevent anything that generates help from requirements lists from emitting text based on that requirement. It wouldn't change gameplay at all.

Ruleset authors could use this reactively to suppress unhelpful help, and proactively on requirements that they've already documented.

Jacob Nevins <jtn>
Project Administrator

 

(Note: upload size limit is set to 1024 kB, after insertion of the required escape characters.)

Attach File(s):
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -unavailable- added by persia (Posted a comment)
  • -unavailable- added by jtn (Submitted the item)
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    No Changes Have Been Made to This Item
    Show feedback again

    Back to the top


    Powered by Savane 3.1-cleanup