[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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



On 04/06/2016 01:21 PM, Wouter Verhelst wrote:
> 
>> * 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.

Most contributors are either familiar with the document conventions, or
are copy-pasting, so it will probably be correctly done either way (as
long as the document starts from a consistent all-bold or no-bold state).

> - RFC2119 doesn't use bold (mostly because RFCs are plain text, anyway,
>   but hey).

The RFC-to-html converters that add bold as a post-processing pass are
optional.

> - It's more type work.

That one is true, particularly if a post-process pass can do the work.

> - Bold *and* uppercase isn't that much stronger than "just" uppercase, I
>   think.

I tend to agree with this one; ALL_CAPS is enough to call attention to
the word used in normative sense vs. in casual language.  I'm 50:50 on
whether bold makes it better (I won't object to bold, but I wouldn't
have proposed it either).

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

I'll leave it to others to make the final decision on boldness; but
definitely agree that the normative changes should be separate (and go
in now) from the typographical changes (whether or not we decide to take
the bold).

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

Attachment: signature.asc
Description: OpenPGP digital signature


Reply to: