Re: [Nbd] [PATCH] docs/proto.md: Clarify SHOULD / MUST / MAY etc

[Wouter Verhelst <w@...112...>]

I just merged three other patches, and now this won't apply anymore:

error: patch failed: doc/proto.md:393
error: doc/proto.md: patch does not apply
Patch failed at 0001 docs/proto.md: Clarify SHOULD / MUST / MAY etc
The copy of the patch that failed is found in: .git/rebase-apply/patch

(which is pretty much everything)

On Wed, Apr 06, 2016 at 05:58:09PM +0100, Alex Bligh wrote:
> * Clarify that SHOULD / MUST / MAY etc. when in capitals have an
>   RFC 2119 meaning using the wording within that RFC.

Sure. Making it a link to the actual RFC (as Eric suggested) seems like
a good idea.

> * Put the above terms in bold.

I'm a bit in dubio about this bit:

- It's something that will tend to be forgotten, which would then result
  in a text with some things in bold and some things not in bold, which
  would be confusing.
- RFC2119 doesn't use bold (mostly because RFCs are plain text, anyway,
  but hey).
- It's more type work.
- Bold *and* uppercase isn't that much stronger than "just" uppercase, I
  think.
- Typographically, I am of the opinion that overdoing the boldness (no
  pun intended) makes a text harder to read, mostly because it tends to
  be somewhat distracting

I'll readily admit that it's all a bit weak, which is why I say "in
dubio".

Thoughts?

> * Fix some lowercase use of these words which actually were
>   meant to be uppercase.
> 
> * Fix some lowercase 'should' which clearly meant 'MUST'; where
>   it's not obvious, I've made them 'SHOULD' or left them as is.

This mixes typographical changes with normative changes in one and the
same commit, which makes the normative changes harder to spot (and
therefore makes their review harder). Please don't do that; even if you
believe the normative changes to be bugs (or at the very least not
controversial), that *could* theoretically be because you misunderstand
their reasoning, or don't know the background...

-- 
< ron> I mean, the main *practical* problem with C++, is there's like a dozen
       people in the world who think they really understand all of its rules,
       and pretty much all of them are just lying to themselves too.
 -- #debian-devel, OFTC, 2016-02-12