Documentation Conventions for lines wrapping and indentation in authored work
draft-wu-netmod-yang-xml-doc-conventions-05

Document Type Active Internet-Draft (individual)
Last updated 2018-06-16
Stream (None)
Intended RFC status (None)
Formats plain text xml pdf html bibtex
Stream Stream state (No stream defined)
Consensus Boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date
Responsible AD (None)
Send notices to (None)
Netmod Working Group                                               Q. Wu
Internet-Draft                                                    Huawei
Intended status: Best Current Practice                         A. Farrel
Expires: December 18, 2018                              Juniper Networks
                                                               B. Claise
                                                     Cisco Systems, Inc.
                                                           June 16, 2018

Documentation Conventions for lines wrapping and indentation in authored
                                  work
              draft-wu-netmod-yang-xml-doc-conventions-05

Abstract

   Many documents that define YANG modules or YANG fragments also
   include protocol message instance data examples.

   IETF documentation has specific limits on line length (73 characters)
   and some YANG fragment example or protocol message instance data
   examples such as XML encoded YANG data node instance 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 authored
   work to be presented in IETF documentation when authored work such as
   YANG fragment or protocol message instance data example would
   otherwise exceed the maximum line length and provide consistent
   representation of authored work within an Internet-Draft or RFC.
   There are no implications in this document for YANG tools: this
   document does not change the rules for presenting authored work in
   data files or in the wire.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

Wu, et al.              Expires December 18, 2018               [Page 1]
Internet-Draft       YANG Documentation Conventions            June 2018

   This Internet-Draft will expire on December 18, 2018.

Copyright Notice

   Copyright (c) 2018 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Conventions Used in this Document . . . . . . . . . . . . . .   3
     2.1.  Glossary of New Terms . . . . . . . . . . . . . . . . . .   4
   3.  Long line wrapping Example  . . . . . . . . . . . . . . . . .   4
   4.  Objectives  . . . . . . . . . . . . . . . . . . . . . . . . .   5
   5.  Line wrapping and indentation document convention . . . . . .   5
     5.1.  Long line wrapping  . . . . . . . . . . . . . . . . . . .   6
     5.2.  Line unwrapping . . . . . . . . . . . . . . . . . . . . .   7
     5.3.  Auto indentation and dedentation  . . . . . . . . . . . .   8
   6.  Limitation and complexity . . . . . . . . . . . . . . . . . .   8
     6.1.  Limitations . . . . . . . . . . . . . . . . . . . . . . .   8
     6.2.  Complexity  . . . . . . . . . . . . . . . . . . . . . . .   9
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .   9
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   9
   9.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   9
   10. Normative References  . . . . . . . . . . . . . . . . . . . .  10
   Appendix A.  Representing XML and JSON Encodings of Metadata
                Annotations  . . . . . . . . . . . . . . . . . . . .  10
   Appendix B.  Auto-wrapping tool code  . . . . . . . . . . . . . .  11
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  15

1.  Introduction

   When documenting authored work such as YANG fragments example of
   example of YANG module represented in XML encoding it is possible
   that the representation of these authored work will exceed the
   available line length.  Indentation may further aggravate this issue.
Show full document text