Follow-up Comment #2, patch #4723 (project freeciv):

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


Reply to this item at:


  Message sent via/by Gna!

Freeciv-dev mailing list

Reply via email to