On 23 April 2013 03:39, Emmet Hikory <per...@shipstone.jp> wrote: > I had two items on my TODO: one about cleaning up README.rulesets to > address some of the inaccuracies that have crept in over time and one > about updating/unifying all the general class comments in the individual > rulesets. Having gotten through unification of the in-ruleset comments > about buildings, specialists, and citystyles, I was reminded to update > README.rulesets in relation to patch #3869, and wondered why the > documentation is separated in the way that it is. > > I would think that it would be easier to maintain all the ruleset > documentation in README.rulesets, rather than in the individual ruleset > files (simply from a duplication-avoidance strategy), but given the > state of the documentation in each place, suspect that past experience > has shown the opposite to be more true. > > If I am planning to rewrite README.rulesets anyway, is it worth > importing all the detail information from the ruleset comments, and > referencing README.rulesets therein, with an expectation that future > patches can be strongly encouraged to also update the docs, or is it > believed that this isn't going to work, and I should continue to proceed > with updates to both sets of documentation? > > - Ruleset comments are what someone copying one of our supplied rulesets as base of their modification reads. (S)he is much more unlikely to check some detail from separate document than reading it from the very file (s)he is editing. At least classic (or whatever is our default ruleset at the time) should have everything documented. - I see README.rulesets more of as overview of what rulesets are, containing thngs that apply to all ruleset files (such as inifile syntax) that do not fit in comments of any particular ruleset.
_______________________________________________ Freeciv-dev mailing list Freecivfirstname.lastname@example.org https://mail.gna.org/listinfo/freeciv-dev