Subject: [netmod] Summary for the busy : draft-wu-netmod-yang-xml-doc-conventions-00.txt

From: "Adrian Farrel" <[email-masked]>
Date: Mon, 29 Jan 2018 15:49:39 -0000

Hi,

Just a summary for those of you who are busy...

May YANG module documents include examples in XML.

Sometimes there are line length problems caused by the 73 character limit.

Different documents have adopted different ways around this as special cases.

It would be useful to have a generic approach so that all documents have the same look and feel. It has also been suggested that this might ease auto-verification of examples, but that might be a challenge for other reasons.

We have not included JSON in this document. JSON is somewhat more compact, but the same issue could arise, so we do plan to look at this in the future.

Thoughts would be most welcome.

Adrian

> A new version of I-D, draft-wu-netmod-yang-xml-doc-conventions-00.txt
> has been successfully submitted by Qin Wu and posted to the IETF repository.
> 
> Name:		draft-wu-netmod-yang-xml-doc-conventions
> Revision:	00
> Title:		Documentation Conventions for Expressing YANG in XML
> Document date:	2018-01-26
> Group:		Individual Submission
> Pages:		9
> URL:            https://www.ietf.org/internet-drafts/draft-wu-netmod-yang-xml-
> doc-conventions-00.txt
> Status:         https://datatracker.ietf.org/doc/draft-wu-netmod-yang-xml-doc-
> conventions/
> Htmlized:       https://tools.ietf.org/html/draft-wu-netmod-yang-xml-doc-
> conventions-00
> Htmlized:       https://datatracker.ietf.org/doc/html/draft-wu-netmod-yang-xml-
> doc-conventions-00
> 
> 
> Abstract:
>    Many documents that define YANG modules also include examples
>    presented in XML.
> 
>    IETF documentation has specific limits on line length and some XML
>    examples have to include line wraps that would not normally be
>    allowed according to the XML representation rules of RFC7950 and
>    RFC7952.
> 
>    This document lays out documentation conventions that allow YANG
>    examples to be presented in IETF documentation when leaf node
>    encoding would otherwise exceed the maximum line length.  There are
>    no implications in this document for YANG parsers: this document does
>    not change the rules for presenting YANG models or for encoding YANG
>    in data files or in the wire.