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

[Alex Bligh <alex@...872...>]

Wouter,

On 6 Apr 2016, at 20:21, Wouter Verhelst <w@...112...> wrote:

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

Eric and I are keeping you busy :-)

>> * 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?

Well, if you want a look, it's here:
  https://github.com/abligh/nbd/blob/fix-formatting/doc/proto.md

Personally I prefer it. There was an RFC-as-HTML site which
did this which was sort of the inspiration.

I think the best thing for me to do is to remove the changes
that put things into bold in the first instance (they were
largely done automatically as you might guess).

This will leave changes that are almost all normative (if
only correcting a typo type of normative). I'll do that
as a v3.

If you decide you like the bold, I can fix that as a separate
patch which does nothing but 'fix bold'. I'm not that fussed!

>> * 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...

... see above.

-- 
Alex Bligh