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: <http://gna.org/patch/?4723> _______________________________________________ Message sent via/by Gna! http://gna.org/ _______________________________________________ Freeciv-dev mailing list Freecivfirstname.lastname@example.org https://mail.gna.org/listinfo/freeciv-dev