idnits 2.17.1 draft-wu-netmod-yang-xml-doc-conventions-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 6 instances of too long lines in the document, the longest one being 40 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 156 has weird spacing: '... Indent used ...' -- The document date (June 5, 2018) is 2151 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 554 == Unused Reference: 'RFC8340' is defined on line 436, but no explicit reference was found in the text == Unused Reference: 'XML' is defined on line 440, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Netmod Working Group Q. Wu 3 Internet-Draft Huawei 4 Intended status: Best Current Practice A. Farrel 5 Expires: December 7, 2018 Juniper Networks 6 B. Claise 7 Cisco Systems, Inc. 8 June 5, 2018 10 Documentation Conventions for lines wrapping and indentation in authored 11 work 12 draft-wu-netmod-yang-xml-doc-conventions-03 14 Abstract 16 Many documents that define YANG modules or YANG fragments also 17 include protocol message instance data examples. 19 IETF documentation has specific limits on line length (73 characters) 20 and some YANG fragment example or protocol message instance data 21 examples such as XML encoded YANG data node instance examples have to 22 include line wraps that would not normally be allowed according to 23 the XML representation rules of RFC7950 and RFC7952. 25 This document lays out documentation conventions that allow authored 26 work to be presented in IETF documentation when authored work such as 27 YANG fragment or protocol message instance data example would 28 otherwise exceed the maximum line length and provide consistent 29 representation of authored work within an Internet-Draft or RFC. 30 There are no implications in this document for YANG tools: this 31 document does not change the rules for presenting authored work in 32 data files or in the wire. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on December 7, 2018. 50 Copyright Notice 52 Copyright (c) 2018 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 68 2. Conventions Used in this Document . . . . . . . . . . . . . . 3 69 2.1. Glossary of New Terms . . . . . . . . . . . . . . . . . . 4 70 3. Long line wrapping Example . . . . . . . . . . . . . . . . . 4 71 4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5 72 5. Line wrapping and indentation document convention . . . . . . 5 73 5.1. Long line wrapping . . . . . . . . . . . . . . . . . . . 6 74 5.2. Line unwrapping . . . . . . . . . . . . . . . . . . . . . 7 75 5.3. Auto indentation and dedentation . . . . . . . . . . . . 7 76 6. Limitation and complexity . . . . . . . . . . . . . . . . . . 8 77 6.1. Limitations . . . . . . . . . . . . . . . . . . . . . . . 8 78 6.2. Complexity . . . . . . . . . . . . . . . . . . . . . . . 9 79 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 80 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 81 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 82 10. Normative References . . . . . . . . . . . . . . . . . . . . 9 83 Appendix A. Representing XML and JSON Encodings of Metadata 84 Annotations . . . . . . . . . . . . . . . . . . . . 10 85 Appendix B. Auto-wrapping tool code . . . . . . . . . . . . . . 11 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 88 1. Introduction 90 When documenting authored work such as YANG fragments example of 91 example of YANG module represented in XML encoding it is possible 92 that the representation of these authored work will exceed the 93 available line length. Indentation may further aggravate this issue. 94 The line wrapping is needed for formatting purposes, however 95 different document author may take different ways to wrap line which 96 makes difficult to improve the readability and interoperability of 97 published YANG data models. 99 This document lays out documentation conventions that allow authored 100 work to be presented in IETF documentation when authored work such as 101 YANG fragment or protocol message instance data example would 102 otherwise exceed the maximum line length and provide consistent 103 representation of authored work within an Internet-Draft or RFC. 105 Document conventions defined in this document are not representative 106 of how the Authored work must be presented to a software component or 107 carried on the wire. There are no implications in this document for 108 YANG tools(e.g., libyang parser: this document does not change the 109 rules for presenting YANG models or for encoding YANG in data files 110 or in the wire. 112 2. Conventions Used in this Document 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 116 "OPTIONAL" in this document are to be interpreted as described in BCP 117 14 [RFC2119] [RFC8174] when, and only when, they appear in all 118 capitals, as shown here. 120 The following terms are defined in [RFC7950] and are not redefined 121 here: 123 o data node 125 o leaf 127 o leaf-list 129 o instance 131 The following term is defined in [RFC7951] and [RFC7952] and are not 132 redefined here: 134 o data node Instance 136 o data node identifier 138 The following terms are defined in [RFC8340]and 139 [I-D.ietf-netmod-rfc6087bis]. 141 2.1. Glossary of New Terms 143 Authored work: A set of text format work representing YANG 144 fragments, and protocol message instance data except YANG Tree 145 Diagrams. 147 Wrap: Convert authored work with long lines not fitting into an 148 Internet-Draft or RFC into authored work with split line fitting 149 into an Internet-Draft or RFC. 151 Unwrap: Re-Convert authored work with split line fitting into an 152 Internet-Draft or RFC back to valid authored work without split 153 line that can be consumed by a software component or carried on 154 the wire. 156 Indent used to describe the distance, or number of blank spaces used 157 to separate a paragraph from the left or right margins. 159 Libyang parser YANG tool and library for parsing and validating YANG 160 schemas and instance data. 162 3. Long line wrapping Example 164 An example of the documentation of a leaf node is shown in Figure 1. 165 The container node is called , any whitespace, 166 carriage returns, or line feeds between the subelements is insignificant, i.e., an implementation MAY insert 168 whitespace, carriage return, or line feed characters between 169 subelements. The leaf is called "long-leaf-node-label" and is 170 assigned the value "long-leaf-node-value". As can be seen in the 171 example, this fits on one line. However it would only take the 172 addition of a few more characters to the node label or value for the 173 example to overflow the 73 character limit if the line of leaf node 174 instance is indented (e.g., start below with a 175 whitespace offset of two characters. . 177 178 long-leaf-node-value 179 181 Figure 1: A Simple Leaf Node Example 183 For the sake of documentation purpose, the representation shown in 184 Figure 2 SHALL be considered as equivalent to that shown in Figure 1, 185 but when a document uses this convention it MUST also include the 186 text shown in Figure 3. Note that the first example representation 187 in figure 2 is more easily parsed by a human reader than the second 188 example in figure 2. 190 191 \ 192 long-leaf-node-value \ 193 194 195 Or 196 197 long-leaf-node-value 199 201 Figure 2: A Split Leaf Node Example 203 4. Objectives 205 In order to allow authored work to be presented in IETF documentation 206 when authored work such as YANG fragment or protocol message instance 207 data example would otherwise exceed the maximum line length and 208 provide consistent representation of the authored work within an 209 Internet-Draft or RFC, the following design criteria are used: 211 o Allow automatic wrapping line when any line presented in the 212 authored work of I-D or RFCs exceed the maximum line length. 214 o Allow automatic unwrapping line in the artwork when the artwork 215 needs to be presented to a software component or carried on the 216 wire. 218 5. Line wrapping and indentation document convention 220 When the representation of an authored work (e.g.,a leaf node 221 instance representation) in an example would result in a line being 222 longer than the maximum line length for an IETF document the long 223 line must be split and presented on more than one lines. The new 224 line may be indented, if necessary, so that it starts below the first 225 line with a whitespace offset of two characters, which improve 226 readability and interoperability of published YANG data models. 228 When these authored work with split lines needs to be fed into 229 software component or carried in the wire, these authored work with 230 split lines should be unwrapped and reversed into the valid authored 231 work with long line. If indentation is applied to authored work with 232 split lines, the indentation should be removed during unwrapped 233 process. 235 5.1. Long line wrapping 237 Long line wrapping most likely to happen when the authored work 238 example such as leaf node contains built-in type string or datetime 239 or container node and list node includes metadata attributes. 240 Indeed, if this problem arises for other YANG types it may be 241 indicative of poorly chosen YANG type values, and the YANG 242 definitions should be revised before applying document convention for 243 line wrapping defined in this document. 245 In the case of long line exceeding 73 characters, the following long 246 line wrapping conventions MUST be observed: 248 o Split long line in the authored work (e.g.,leaf node instance, 249 YANG data node instance containing metadata annotation attributes) 250 exceeding 73 characters limits with the backslash ("\") and use 251 backslash ("\")to indicate wrapping at the end of the line. The 252 broken line MUST be terminated with a backslash ("\") without the 253 addition of any additional space before the backslash and with no 254 further characters after the backslash. 256 o Any continuation lines or new line MUST align with the first line 257 and may chose not be indented with any whitespace offset. 259 o When a backslash appears in any line not used for split line, the 260 representation of this artwork MUST be arranged so that this 261 backslash is not the final character of a broken line. 263 Furthermore, whenever a document uses long line wrapping conventions 264 it MUST also include the following boilerplate text : 266 [!!! '\' line wrapping is for formatting only and adopt the conventions 267 shown in BCPXX [RFCYYYY]] 269 RFC Editor Note: Please replace XX and YYYY with the numbers assigned 270 for this document. 272 Figure 3 274 Figure 4 shows an example of Backslash appearing in the long line not 275 used for split line. 277 Punctuation is important. 278 As are line feeds.Some characters are special,e.g., the backslash\ .Don't forget. 280 Figure 4: An Example Leaf Node With a Complex String Value 282 Figure 5 shows a semantically equivalent representation of the 283 example. 285 Punctuation is important. As \ 286 are line feeds.Some characters are special,e.g., the backslash \.\ 287 Don't forget. 289 Figure 5 291 5.2. Line unwrapping 293 If line wrapping is done for formatting purposes, the line wrapping 294 in the authored work should be reversed back or unwrapped before the 295 authored work is fed into software component for validation or 296 carried in the wire. Therefore line unwrapping help remove backslash 297 and additional carriage return or line feed character and make 298 unwrapped authored work to be effectively compliant with the tool. 299 The line wrapping for formatting purpose is indicated by the above 300 boilerplate text. To unwrap line, the following conventions must be 301 observed: 303 o Consecutive split lines in the authored work with backslash at the 304 end of the line should be merged into one long line, the last 305 split line in Consecutive split lines should not be terminated 306 with backslash. 308 o If a backslash character ("\") doesn't appear at the end of the 309 line within authored work, it should not be stripped. 311 o If a backslash character ("\") appears at the end of the line 312 within authored work, it should be stripped. In the meanwhile, if 313 and only if it is immediately followed by a carriage return or 314 line feed character then all carriage return, line feed, and 315 whitespace characters should be stripped until the next character 316 is encountered. 318 5.3. Auto indentation and dedentation 320 Consistent indentation should be used for all authored work in the 321 I-D and RFCs, e.g., if a space or tab characters are used to index 322 the text in the long line during wraping process, the space and tab 323 characters used for indentation should be removed during unwrapping 324 process. If the new line or continuation line indented with a 325 whitespace offset of two characters during wrapping process, the 326 indentation with a whitespace offset of two characters should be 327 removed during unwrapping process. 329 6. Limitation and complexity 331 6.1. Limitations 333 All modules need to be extracted YANG modules from an Internet Draft 334 or RFC and then validated before submission in an Internet Draft. 335 However we don't have automation tool to extract authored work such 336 as YANG fragments or protocol message instance. To extract authored 337 work, similar The strings "" and "" MUST be 338 defined and populated to identify each authored work component, e.g., 339 the boilerplate text in Section 5 can be used to indicate the 340 begining of authored work. 342 Applying wrapping and unwrapping functionality to example YANG module 343 or YANG module extracted using existing tool also has limitation, 344 even introduce confusion, e.g., 346 1. The data definition description statement has long line exceeding 347 73 characters, it should be wrapped without using backslash as 348 termination point. 350 " 351 grouping link-ref { 352 description 353 "This grouping can be used to reference a link in a specific 354 network. Although it is not used in this module, it is 355 defined here for the convenience of augmenting modules."; 356 " 358 2. Another example is when a plus character ("+") is used to 359 concatenate two quoted string into one string, using backslash to 360 split the line Confuses with using a plus character ("+") to 361 split the line. 363 " 364 container dhcp-relay { 365 when "derived-from-or-self(../address-allocation-type, "+ 366 "'l3vpn-svc:provider-dhcp-relay')" { 367 description 368 "Only applies when provider is required to implement 369 DHCP relay function."; 370 } 371 " 373 6.2. Complexity 375 We can build tool to support auto wrap and auto indentation. However 376 if the tool is designed to understand various encodings, e.g., XML 377 encoding, JSON encoding or metadata annotation, it add a lot of 378 complexity to build such tool, therefore the only choice to make tool 379 understand various encodings, is to build encoding specific tool 380 which doesn't scale well. If the tool understands metadata 381 annotation, we can decide where to insert backslash to split the 382 lines: either inserted between metadata Attributes or insert at any 383 place when the long line exceeding 73 characters limits. See more 384 complexity details in Appendix A. 386 7. Security Considerations 388 There is no direct security impact related to the XML/JSON encoding 389 documentation convention described in this document. However, 390 attempting to provide actual XML/JSON using the documentation 391 conventions described in this document would have unpredictable 392 results. The risk here is that someone uses an example as a template 393 for actual XML/JSON. The mandatory boilerplate text provides a 394 mitigation against this risk. 396 8. IANA Considerations 398 There are no IANA requests or assignments included in this document. 400 9. Acknowledgements 402 Thanks to Kent Watsen for discussions that kept us close to being on 403 the right track. Additional thanks to John Scudder for flagging some 404 nits, Martin Bjorklund, Charles Eckel, Robert Wilton and many others 405 for valuable comments and review, special thanks Xiongjie to help 406 support automation tool building. 408 10. Normative References 410 [I-D.ietf-netmod-rfc6087bis] 411 Bierman, A., "Guidelines for Authors and Reviewers of YANG 412 Data Model Documents", draft-ietf-netmod-rfc6087bis-20 413 (work in progress), March 2018. 415 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 416 Requirement Levels", BCP 14, RFC 2119, 417 DOI 10.17487/RFC2119, March 1997, 418 . 420 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 421 RFC 7950, DOI 10.17487/RFC7950, August 2016, 422 . 424 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 425 RFC 7951, DOI 10.17487/RFC7951, August 2016, 426 . 428 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 429 RFC 7952, DOI 10.17487/RFC7952, August 2016, 430 . 432 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 433 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 434 May 2017, . 436 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 437 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 438 . 440 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and 441 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 442 Edition)", World Wide Web Consortium Recommendation REC- 443 xml-20081126, November 2008, 444 . 446 Appendix A. Representing XML and JSON Encodings of Metadata Annotations 448 [RFC7952] section 5.1 and section 5.2 provide an encoding rule for 449 metadata annotations in XML and JSON respectively. 451 When an example XML representation of a leaf node element that 452 includes metadata attributes results in a line being longer than the 453 maximum number of characters allowed in a line of an IETF document, 454 the value of the leaf node must be split across more than one line. 456 Where possible, all line breaks should be inserted between metadata 457 attributes. Continuation lines MUST align with the first line and 458 not be indented with any whitespace. The leading and trailing 459 whitespace of each line MUST be ignored. Figure 6 gives a XML 460 example. 462 When an example JSON representation of a leaf node element that 463 includes metadata attributes starting with the "@" character results 464 in a line being longer than the maximum number of characters allowed 465 in a line of an IETF document,the value of the leaf node must be 466 split across more than one line. Continuation lines MUST align with 467 the first line and indented with one whitespace character. The 468 leading and trailing whitespace of each line MUST be ignored. 469 Figure 7 gives a JSON example. 471 Whenever this documentation convention is used, the boilerplate text 472 shown in Figure 3 MUST be present in the document using the 473 convention. 475 477 ... 478 480 Figure 6: An XML Example Leaf Node With Metadata Split Across Lines 482 "cask": { 483 "@": { 484 "example-org-example-last-modified:last-modified":\ 485 "2015-09-16T10:27:35+02:00" 486 }, 487 ... 488 } 490 Figure 7: A JSON Example Leaf Node With Metadata Split Across Lines 492 Appendix B. Auto-wrapping tool code 494 We provide examples of python code for aspects of line wrapping and 495 unwrapping algorithms. There may be other implementation methods 496 that are faster in particular operating environments or have other 497 advantages. These implementation notes are for informational 498 purposes only and are meant to clarify the this specification for 499 line wrapping and unwrapping. 501 #!/usr/bin/env python2.7 502 # -*- coding: utf-8 -*- 503 """Qin Wu, 2018-06-02 504 Autowrapper.py uses Text Wrap Module as library. 505 Text Wrap module provides two convenience functions, wrap() and fill(), as well as 506 TextWrapper, the class that does all the work, and a utility function dedent(). If 507 you're just wrapping or filling one or two text strings, the convenience functions 508 should be good enough; otherwise, you should use an instance of TextWrapper for 509 efficiency. 511 https://github.com/python/cpython/blob/2.7/Lib/textwrap.py 512 """ 513 import textwrap 514 import string, re 515 import argparse 516 import os.path 517 import sys, getopt 519 def auto_wrap(input_file, dst_file): 521 finput=open(input_file, "r") 522 alllines=finput.readlines() 523 finput.close() 524 foutput = 0 525 output_file = dst_file 526 foutput = open(output_file, 'a') 527 for eachline in alllines: 528 bc = textwrap.fill(eachline,73) 529 tmplines = bc.split('\n') 530 tmplen = len(tmplines) 531 if tmplen == 1 : 532 foutput.writelines(bc) 533 foutput.writelines('\n') 534 else : 535 i = 0 536 while i < tmplen-1 : 537 foutput.writelines(tmplines[i]) 538 foutput.writelines('\\') 539 foutput.writelines('\n') 540 i += 1 541 foutput.writelines(tmplines[tmplen-1]) 542 foutput.writelines('\n') 543 foutput.close 545 def auto_unwrap(input_file, dst_file) : 546 finput=open(input_file, "r") 547 alllines=finput.readlines() 548 finput.close() 549 foutput = 0 550 output_file = dst_file 551 foutput = open(output_file, 'a') 552 for eachline in alllines: 553 bc = eachline.split('\\') 554 foutput.writelines(bc[0]) 556 if __name__ == "__main__": 557 auto_wrap("in-1.txt","out-1.txt") 558 auto_unwrap("out-1.txt", "out-2.txt") 560 Authors' Addresses 562 Qin Wu 563 Huawei 564 101 Software Avenue, Yuhua District 565 Nanjing, Jiangsu 210012 566 China 568 Email: bill.wu@huawei.com 570 Adrian Farrel 571 Juniper Networks 573 Email: afarrel@juniper.net 575 Benoit Claise 576 Cisco Systems, Inc. 577 De Kleetlaan 6a b1 578 1831 Diegem 579 Belgium 581 Phone: +32 2 704 5622 582 Email: bclaise@cisco.com