Sean Whitton <spwhit...@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 (r...@debian.org) <https://www.eyrie.org/~eagle/>