Re: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04
Martin Bjorklund <mbj@tail-f.com> Wed, 27 June 2018 20:43 UTC
Return-Path: <mbj@tail-f.com>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 9F2B7130E2D for <netmod@ietfa.amsl.com>; Wed, 27 Jun 2018 13:43:16 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.901
X-Spam-Level:
X-Spam-Status: No, score=-1.901 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 9XT2c7n9Lh0n for <netmod@ietfa.amsl.com>; Wed, 27 Jun 2018 13:43:14 -0700 (PDT)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id 84899130EA0 for <netmod@ietf.org>; Wed, 27 Jun 2018 13:43:14 -0700 (PDT)
Received: from localhost (h-80-27.A165.priv.bahnhof.se [212.85.80.27]) by mail.tail-f.com (Postfix) with ESMTPSA id 1EA9A1AE0389; Wed, 27 Jun 2018 22:43:12 +0200 (CEST)
Date: Wed, 27 Jun 2018 22:43:11 +0200
Message-Id: <20180627.224311.2057585548075314668.mbj@tail-f.com>
To: kwatsen@juniper.net
Cc: bill.wu@huawei.com, netmod@ietf.org
From: Martin Bjorklund <mbj@tail-f.com>
In-Reply-To: <E777E7B0-5A9C-4397-83D4-DBA2BA8510AD@juniper.net>
References: <21CFADF6-9FB8-4B0B-A7FC-517FDDAF6F8C@juniper.net> <20180626.220807.1407068226011761897.mbj@tail-f.com> <E777E7B0-5A9C-4397-83D4-DBA2BA8510AD@juniper.net>
X-Mailer: Mew version 6.7 on Emacs 24.5 / Mule 6.0 (HANACHIRUSATO)
Mime-Version: 1.0
Content-Type: Text/Plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/t-6lXnL_EmUwNBs_5wohxs6aeYQ>
Subject: Re: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.26
Precedence: list
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 27 Jun 2018 20:43:17 -0000
Kent Watsen <kwatsen@juniper.net> wrote: > > > >> Those are torture tests, but they due illustrate the one case where having > >> the '\\n' on the fold column would've been illegal input (and hence the '\' > >> was replaced with a 'x'). Great for internal algorithm validation, but > >> perhaps unnecessary for the example in the text. Or maybe enhance the > >> comments above these lines to explain why they're there? > > > > I suggest you remove this. > > Okay. > > > >> > I like the algorithm in the other draft better - it had variable > >> > placement of the line break ("\\n" sequence), and variable > >> > indentation. > >> > >> How can you automated variable placement of the line-break, assuming no > >> awareness of the file format? Additionally, be aware that variable '\n' > >> placement would necessitate pre-scanning the file to ensure *no* line > >> ends in a '\\n', as opposed to just the lines that need folding. > > > > I envision this format being used not just by a program, but also by > > humans trying to construct nice looking examples. > > I really hope humans don't try to do this manually, as the results are > error-prone, and it isn't consistent with the goal of integrating validation > in the build scripts that compile the drafts, for which automated-folding > is needed (see section 3.1). I disagree. I often use my own markup in example files so that I can validate the examples with tools, and then run a script that turns the markup into newlines (in the future: '\' + newline). For example: <namespace><!-- PPL -->urn:ietf:params:xml:ns:yang:ietf-yang-types</namespace> turns into: <namespace>\ urn:ietf:params:xml:ns:yang:ietf-yang-types </namespace> (the <!-- PPL --> is my own markup). Compare with <namespace>urn:ietf:params:xml:ns:yang:ietf-yang-types</n\ amespace> Not sure if this qualifies as "manual folding" or not. > I'm not saying that manual-folding shouldn't > be possible, I'm saying that it is ill-advised, and we shouldn't go out of > our way to support it. I don't think it is difficult to support variable placement of the linebreak. It is already specified in the other draft. > I do not support variable placement of the > line-break. > > [Note: indentation of the beginning of the line is a different issue, and > one that I actually support, assuming it is easily automatable] > > > > Also, I would prefer a description of the format, rather than of one > > algorithm that produces the format. > > Okay, we will look into it. > > > >> >> >> - handle two special case on backslash and space at the end of broken > >> >> >> line in yang-xml-doc-conventions. > >> >> >> - propose to use <WRAPPED TEXT BEGIN><WRAPPED TEXT END> to extract > >> >> >> artwork from I-Ds. > >> >> > > >> >> > The artwork draft proposes only a header, which means that it is not > >> >> > quite clear where the artwork ends. > >> >> > >> >> Interesting point, but I think that artwork-framing is a different problem > >> >> from artwork-folding. If the goal is to support extracting artwork from > >> >> txt-based RFC scripts, regardless if the artwork is folded or not, then we > >> >> could level-up this draft to that role, while still supporting folding. > >> >> > >> >> If we were to add a footer, maybe something like this: > >> >> > >> >> ===padding=== End Folding per BCP XX (RFC XXXX) ===padding=== > >> >> > >> >> where the "padding" fills in '=' characters until the max-line width is > >> >> reached (same as how the header is done). > >> > > >> > Ok. > >> > >> I assume that you're okay-ing the proposed footer, but the real question is > >> if we should expand the scope of this draft to include artwork-framing also? > > > > I think I would prefer if there is also a footer. > > Why? Do you propose the same for all artwork, regardless if it's been folded > or not? To me, these are different issues. Hmm, good point. Maybe ignore for now. /martin > >> >> >> In the artwork draft, section 5.3, you write: > >> >> >> > >> >> >> This line is self-describing in > >> >> >> three ways: use of '\' character, identification of BCP/RFC, and > >> >> >> identification of what the maximum line length is for the artwork. > >> >> >> > >> >> > I was confused about this maximum line length; it seems you define the > >> >> > maximum line length ot be 53, but that seems too limiting, and indeed > >> >> > in the example in 5.4 the max line length is 69. (BTW, the example is > >> >> > missing in the draft, as is the shell script in Appendix A). In any > >> >> > case, I don't see how the header identifies the max line length. > >> >> > >> >> The draft says that the *minimal* header string is 53-characters). We > >> >> can make it less if needed, but it involves needing to fold the header > >> >> itself, which could become messy. Thoughts? > >> >> > >> >> Per the line just before the one quoted above, this line is '=' padded > >> >> on both sides until reaching the max value. Apparently, this isn't > >> >> clear enough in the text, or do you think it's okay now? > >> > > >> > The draft says: > >> > > >> > The header is two lines long. > >> > > >> > The first line is the following 53-character string > >> > > >> > This is what made me confused. I now understand that the idea is to pad > >> > with '='. > >> > >> Right, the full sentence is: > >> > >> The first line is the following 53-character string that has been > >> padded with roughly equal numbers of equal ('=') characters to reach > >> the artwork's maximum line length. > >> > >> So, leave as is for now? > > > > Well ... I don't think this text is even correct... The section > > describes the header with the first line being 53 characters. But > > that is just an example. Maybe: > > > > The first line is an N-character string on the following form: > > > > === NOTE: '\' line wrapping per BCP XX (RFC XXXX) === > > > > where N is the artwork's maximum length (the minimum length is > > 53). The string is padded with roughly equal numbers of equal > > ('=') characters in the beginning and end to reach the artwork's > > maximum line length. > > Yes, this is better > > > > ... but as I wrote, I'd prefer a variable-length format. > > Understood, being discussed above. > > > > /martin > > Kent // contributor > > >
- Re: [netmod] Call for adoption request of draft-k… Robert Wilton
- Re: [netmod] Call for adoption request of draft-k… Qin Wu
- Re: [netmod] Call for adoption request of draft-k… Qin Wu
- Re: [netmod] Call for adoption request of draft-k… Martin Bjorklund
- Re: [netmod] Call for adoption request of draft-k… Kent Watsen
- Re: [netmod] Call for adoption request of draft-k… Martin Bjorklund
- Re: [netmod] Call for adoption request of draft-k… Kent Watsen
- Re: [netmod] Call for adoption request of draft-k… Martin Bjorklund
- Re: [netmod] Call for adoption request of draft-k… joel jaeggli
- [netmod] Call for adoption request of draft-kwats… Qin Wu
- Re: [netmod] Call for adoption request of draft-k… Martin Bjorklund
- Re: [netmod] Call for adoption request of draft-k… Kent Watsen
- Re: [netmod] Call for adoption request of draft-k… Qin Wu
- Re: [netmod] Call for adoption request of draft-k… Kent Watsen
- Re: [netmod] Call for adoption request of draft-k… Martin Bjorklund
- Re: [netmod] Call for adoption request of draft-k… Bob Harold
- Re: [netmod] Call for adoption request of draft-k… Robert Wilton
- Re: [netmod] Call for adoption request of draft-k… Kent Watsen
- Re: [netmod] Call for adoption request of draft-k… Kent Watsen
- Re: [netmod] Call for adoption request of draft-k… Robert Wilton
- Re: [netmod] Call for adoption request of draft-k… Martin Bjorklund