Re: [netmod] Call for adoption request of draft-kwatsen-netmod-artwork-folding-04
Martin Bjorklund <mbj@tail-f.com> Tue, 26 June 2018 18:58 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 3AE90131102 for <netmod@ietfa.amsl.com>; Tue, 26 Jun 2018 11:58:09 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.9
X-Spam-Level:
X-Spam-Status: No, score=-1.9 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_PASS=-0.001, URIBL_BLOCKED=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 MvQzDBeaHtWX for <netmod@ietfa.amsl.com>; Tue, 26 Jun 2018 11:58:07 -0700 (PDT)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id 6BEB9131101 for <netmod@ietf.org>; Tue, 26 Jun 2018 11:58:07 -0700 (PDT)
Received: from localhost (h-155-4-133-90.NA.cust.bahnhof.se [155.4.133.90]) by mail.tail-f.com (Postfix) with ESMTPSA id ADE441AE0311; Tue, 26 Jun 2018 20:58:06 +0200 (CEST)
Date: Tue, 26 Jun 2018 20:58:07 +0200
Message-Id: <20180626.205807.1642470222068426969.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: <34C78C9F-57A9-4234-8F30-39F69F0B2F04@juniper.net>
References: <B8F9A780D330094D99AF023C5877DABA9AEB4274@nkgeml513-mbx.china.huawei.com> <20180626.122602.1952551623315308243.mbj@tail-f.com> <34C78C9F-57A9-4234-8F30-39F69F0B2F04@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/tiL_rNuTiBXuXFBnsMnEqJwjvuU>
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: Tue, 26 Jun 2018 18:58:09 -0000
Kent Watsen <kwatsen@juniper.net> wrote: > > Hi Martin, > > First, I just posted -05 to address the missing artwork: > https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-05. Thanks! (The exmaples with just a string of '\' are highy confusing. Unclear what they try to tell me... probably that the alg is much more difficult than I originally thought ;-) > See below for more comments. > > Kent // contributor > > > ===== original message ===== > > > Hi, > > > > I support this work. See below for some comments. > > > > Qin Wu <bill.wu@huawei.com> wrote: > >> Dear WG, > >> > >> As you may recall I presented yang-xml-doc-conventions in London. > >> There was strong support for trying to solve the problem and mixed > >> views on the solution, other than that we should do it fast. In the > >> meanwhile, Kent submitted artwork-folding as an alternative solution. > >> > >> The authors of the two drafts decided to combine efforts. After > >> several internal iterations on both drafts, the drafts were becoming > >> more alike than different(both support auto wrapping or auto folding). > >> The artwork-folding draft was selected as a preferred offering basis > >> (i.e., draft-kwatsen-netmod-artwork-folding-04) to the working group > >> to consider for adoption. > >> > >> The primary feature differences remained are: > >> - all folded lines continue of column 0 without two character > >> indentation, i.e., whether auto indentation should be supported. > > > > I really liked the flexible indentation in the other draft. I suggest > > it is added to this draft. It enhances readability (if the author > > wants it). > > Variable indentation, when the folded-line starts on same column as > the previous line, looks nice. The current yang-xml-doc-conventions > draft has a fixed two-space indent, which would only look nice sometimes > while introducing a surprise factor other times. Hmm, I thought it had variable-length indentation. > Variable indent introduces significant complexity; at least, it's beyond > what can be accomplished by a `sed` one-liner, such as in the current > draft. A fixed two-space indent is possible (easy), but zero-space > indent is more common (less surprising) than a fixed indent. I like the algorithm in the other draft better - it had variable placement of the line break ("\\n" sequence), and variable indentation. Note that your proposed format is just a special case of the format in the other draft, so you can still use your "one-liner" sed to produce your result. > >> - 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. > >> 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 '='. But if we adopt the algorithm in the other draft, we don't need a maximum line length like this. /martin > For what it's worth, I originally had the actually fold-column > (e.g., 69) printed in the header, but it was realized that it was > noise to the reader (humans don't care about the fold column number), > whereas padding the line out provides visually meaningful information > (e.g., one can hover the cursor over the end and then scroll the > document to find all the folds). > > > > > Also, in section 5.2, the first sentence is: > > > > Scan the artwork to see if any line exceeds the desired maximum. > > > > But what is the desired maximum? I assume that the idea is that the > > author first selects a desired max? Maybe add a line that explains > > this, and again write that 69 is a reasonable value for use in I-Ds > > and RFCs. > > Right, the idea is that the author has a target fold-column in mind. > It's an input parameter to the script in the appendix. The max value > defaults to 69. > > I added the following sentence before the "scan" line above: > > Determine the desired maximum line length from input. If no > value is explicitly specified, the value "69" SHOULD be used. > > > > > /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