adding rationale commentary to the policy manual

[Joey Hess <joeyh@debian.org>]

I've long felt that one big failing of the policy manual is that it does not
include any text describing the rationale behind the rules in it. This
leads to problems when newcomers try to figure out why policy is the way it
is (and when one-timers forget), it means there is the potential we will
forget why doing something one way is really a good idea, and change policy
to have it be done another way, without considering the ramifications, and
it probably contributes to us discussing some issues over and over.

So I'd like to lay the groundwork for adding rationales to each bit of
policy. At first we could just add rationale text when we change peices of
policy and add new bits. perhaps later we could go back and try to add
rationales for the existing body of policy as well, and perhaps flag some
existing text that is in policy as being a rationale [2].

The policy manual is a debiandoc sgml document. I think we just need to add
a new rationale tag (either to debiandoc, or to a DTD derived from it). The
tag will contain CDATA [1] and may be ignored when converting the sgml to other
formats, or output in some pleasing manner, whatever.

-- 
see shy jo

[1] Please pardon any XML-isms in this paragraph, I do not know sgml in all
    its glory. :-)
[2] "No program may depend on environment variables to get reasonable
     defaults.  (That's because these environment variables would have to
     be set in a system-wide configuration file like /etc/profile, which is
     not supported by all shells.)" 
     
    becomes
     
    "No program may depend on environment variables to get reasonable
     defaults.  <rationale>These environment variables would have to be
     set in a system-wide configuration file like /etc/profile, which is
     not supported by all shells.</rationale>"