Bug#944920: Revise terminology used to specify requirements

[Russ Allbery <rra@debian.org>]

Sean Whitton <spwhitton@spwhitton.name> writes:

> One issue with using uppercased words is that people might think the
> words have the same meaning as they do in RFCs, which they don't.

> Your idea of marking keywords in bold wouldn't have this problem, and
> maybe it would actually make it /easier/ to write patches because you
> can see more clearly which of your words mean what.

It does have the drawback of being either less obvious or a bit noisy in
the text output format, though, which I suspect is reasonably heavily
used.

I'm not sure our definitions are that far off from the RFC terms.  We're
not defining a protocol, so it's inherently a little different, but there
are some clear equivalents.  And it would avoid reinventing a new
typographic convention.

A long time ago, Manoj proposed a deeper, more comprehensive fix: stop
writing Policy as English prose and instead explicitly state normative
requirements in some sort of numbered, clear fashion, and then add a prose
informative explanation if warranted.  But I'm a bit dubious of that.  Not
only would it be a ton of work, but the more formal phrasing will require
repeating ourself a lot more.

Personally, I think I'm leaning mildly towards the all-caps keywords
because of familiarity and compatibility with a pure text format, although
I could be convinced otherwise.

I do think making this change is a good idea.

> Thinking more, I believe that the issue you're raising here is separate
> from what Russ is trying to achieve in this bug.  The problem you're
> identifying here already exists in Policy, before Russ's change is
> applied.  So maybe we should discuss it separately.

Yes, I'm behind but that was the thing I wanted to say: I'd like to merge
this change (I haven't looked at more recent reviews, since I've been
distracted with work, so I don't know off-hand if it's ready for merging
otherwise) and then tackle this issue separately.  But I do think it's
time to tackle it.

>> BTW I guess the instances of «might» and «shall» need to be converted,
>> or added to the keyword list? What about «may not», or «can», «can't»,
>> «cannot» and «could»? And I'm probably missing other words. :)

> I don't think we need to convert words that don't explicitly appear in
> the keywords list -- "may not" would inherit its meaning from "may"
> being a keyword, wouldn't it?

I think that if the word doesn't appear in the keyword list, it shouldn't
have any normative meaning.  I have intentionally used the words can and
cannot in Policy text precisely because they don't have normative meaning
and don't state Policy requirements.  For example, in:

    If punctuation is desired between the date components, remember that
    hyphen (``-``) cannot be used in native package versions.

the "cannot" is not a normative Policy requirement, just a description of
a logical consequence of a definition stated earlier.

-- 
Russ Allbery (rra@debian.org)              <https://www.eyrie.org/~eagle/>