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 (CEST)
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
> 
> 
>