Re: [yang-doctors] Yangdoctors last call review of draft-ietf-netconf-notification-capabilities-05

[Ladislav Lhotka <[e-mail]>]

[also CCing YANG Doctors]

Balázs Lengyel <[e-mail]> writes:

> Hello Lada,
> See below. See if you can accept my answer.
> Regards Balazs
>

...

>>       - Many enum values are invalid because they contain
>>         leading/trailing whitespace. It would be better to encode the
>>         examples in JSON.
>> BALAZS: I would like to keep the examples as they are.
>> In many previous RFCs lines in XML examples were broken into multiple lines.
>> E.g. 
>> RFC7950 7.16.3
>> rfc8341 A.4
>> rfc8641 4.4.1
>> rfc6022 4.1
>> rfc8525 B
>> rfc8072 A.1.1
>> rfc6243  A.3.1
>> IMHO it is readable. It is better to use longer descriptive names in 
>> YANG, then to use short names just to avoid long lines in XML examples.
>
> The problem with this approach is that it may mislead casual readers into thinking that the whitespace can be freely added to such values.
>
> Lada
>
> BALAZS2:
> IMHO as this is accepted practice (in not one but about every second RFC), and RFC7950 is explicit about the matter, the risk is not that big.

How is RFC 7950 explicit about it? BTW section 7.16.3 doesn't do this - in XPath expressions, extra whitespace is permitted in many places.

Also, it was more tolerable when XML was the only possible representation.

>
> On the other hand my alternatives would be:
> - use shorter, less meaningful schema names - results in less meaningful names

Agreed, not good.

> - use the still draft artwork folding - would like to avoid more dependencies on drafts. If this would be a full RFC the issue would be different.

Understood.

> - add textual remarks about the issue - unusual solution, needs quite a bit of explanation
> - use only JSON examples - IMHO I like XML, and only JSON my surprise some people

I think JSON examples are considerably more human-readable then XML, and I don't know why they should surprise anybody. This data isn't limited to NETCONF, so there is really no reason for not using JSON.

>
> So as a conclusion I would really like to keep the example as is. Can you accept it? If not please advise on what is acceptable for you.

I can live with it.

Lada

> Regards Balazs

-- 
Ladislav Lhotka 
Head, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67