Re: [netmod] artwork folding: dual support modes?

Martin Bjorklund <mbj@tail-f.com> Mon, 04 March 2019 11:49 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 461F0130F2A for <netmod@ietfa.amsl.com>; Mon, 4 Mar 2019 03:49:17 -0800 (PST)
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 6-OvJszoTznb for <netmod@ietfa.amsl.com>; Mon, 4 Mar 2019 03:49:14 -0800 (PST)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id 317211288BD for <netmod@ietf.org>; Mon, 4 Mar 2019 03:49:14 -0800 (PST)
Received: from localhost (unknown [173.38.220.61]) by mail.tail-f.com (Postfix) with ESMTPSA id DEF7E1AE0118; Mon, 4 Mar 2019 12:49:11 +0100 (CET)
Date: Mon, 04 Mar 2019 12:49:12 +0100 (CET)
Message-Id: <20190304.124912.231750494593528236.mbj@tail-f.com>
To: rwilton@cisco.com
Cc: adrian@olddog.co.uk, joelja@bogus.com, netmod@ietf.org
From: Martin Bjorklund <mbj@tail-f.com>
In-Reply-To: <8ddf74d483674c598e52ece716f70d0a@XCH-RCD-007.cisco.com>
References: <3af58c925ad74fbfaaea299877bf992d@XCH-RCD-007.cisco.com> <20190304.094006.527512831015675938.mbj@tail-f.com> <8ddf74d483674c598e52ece716f70d0a@XCH-RCD-007.cisco.com>
X-Mailer: Mew version 6.7 on Emacs 25.2 / Mule 6.0 (HANACHIRUSATO)
Mime-Version: 1.0
Content-Type: Text/Plain; charset=utf-8
Content-Transfer-Encoding: base64
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/dQjLLigVC5Mcufe6ieF0hZaGqZo>
Subject: Re: [netmod] artwork folding: dual support modes?
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.29
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: Mon, 04 Mar 2019 11:49:17 -0000

"Rob Wilton (rwilton)" <rwilton@cisco.com> wrote:
> But this behaviour is still different from the frequently used meaning
> of ‘\’ today in programming languages, which as I know it just splits
> lines and preserves whitespace.

Right, but we're not doing a programming language, we try to fit long
lines in examples into the format required by RFCs, including
indentation.  For example, suppose you have:

  Here's an example:

  foo bar baz \
  buzz

Unfolded, do you think this is:

  foo bar baz buzz

or

  foo bar baz    buzz


> YANG requires a separator character between a keyword and its
> argument.  What happens if the tool happens to split the line between
> the two of them.
> 
> 
> 
> E.g
> 
>                        container\
> 
>   test
> 
> 
> 
> After the artwork folding, this would become
> 
>                        containertest
> 
> 
> 
> This could be mitigated by a smarter folding tool (e.g. split before
> the ‘r’ or after the first space).


1.  Don't use a tool to add line breaks - remember the goal was to
    have a readable example.

2.  Don't use this alg. for YANG modules, since YANG has builtin /
    native support for splitting long lines.


> Or, what if the tool was being used to fold a table that was using
> whitespace to align the columns.  This could easily break if
> whitespace is stripped.

Don't use this alg for tables (or ascii art in general) -- it won't
help readers.


/martin





> 
> 
> 
> Thanks,
> Rob
> 
> 
> 
> 
> 
> -----Original Message-----
> From: Martin Bjorklund <mbj@tail-f.com>
> Sent: 04 March 2019 08:40
> To: Rob Wilton (rwilton) <rwilton@cisco.com>
> Cc: adrian@olddog.co.uk; joelja@bogus.com; netmod@ietf.org
> Subject: Re: [netmod] artwork folding: dual support modes?
> 
> 
> 
> "Rob Wilton (rwilton)" <rwilton@cisco.com<mailto:rwilton@cisco.com>>
> wrote:
> 
> > Hi Adrian,
> 
> >
> 
> > I mostly agree with your last sentence.
> 
> >
> 
> > I think that if you always preserve whitespace then a single slash is
> 
> > fine.  I.e. the single slash just breaks the line, and I think that
> 
> > this matches how editors, programming languages, etc normally behave.
> 
> >
> 
> > What I’m not keen on is using a single slash, and then automatically
> 
> > stripping leading whitespace on the line following a slash.
> 
> 
> 
> And this is the solution that I prefer.  The reason for this is that I
> view examples as something that is there to illustrate some point to
> the reader, and I think that a prettier formatted example with less
> noise helps the reader.  I also think that is most cases, this works
> well; i.e., most cases are _not_ on the form:
> 
> 
> 
>    12345      78990
> 
>           ^-------------- I need a line break here
> 
> 
> 
> 
> 
> For this problem, I prefer a solution that is intuitive and has less
> noise and works for 90% of the cases, than a less intuitive solution
> with more noise that works for 100% of the cases.
> 
> 
> 
> 
> 
> /martin
> 
> 
> 
> 
> 
> 
> 
> >
> 
> > If we want to have control of layout and be able to strip extra
> 
> > whitespace then my argument is that it is better to be explicit, and
> 
> > using two slashes is one way of achieving this.
> 
> >
> 
> > Thanks,
> 
> > Rob
> 
> >
> 
> >
> 
> >
> 
> > From: netmod <netmod-bounces@ietf.org<mailto:netmod-bounces@ietf.org>>
> > On Behalf Of Adrian Farrel
> 
> > Sent: 27 February 2019 09:41
> 
> > To: 'Joel Jaeggli' <joelja@bogus.com<mailto:joelja@bogus.com>>
> 
> > Cc: netmod@ietf.org<mailto:netmod@ietf.org>
> 
> > Subject: Re: [netmod] artwork folding: dual support modes?
> 
> >
> 
> > Complete agreement, Joel.
> 
> >
> 
> > What follows may look better in proportional fonts.
> 
> >
> 
> > With a single slash we can wrap as follows
> 
> >
> 
> > 1234567        9012345
> 
> >
> 
> > Goes to…
> 
> >
> 
> > 1234567    \
> 
> >     9012345
> 
> >
> 
> > …and unwrapping is easy.
> 
> >
> 
> > However, if I want to manually wrap the line with indentation
> 
> >
> 
> > The quick brown fox jumps over the lazy dog
> 
> >
> 
> > ..going to…
> 
> >
> 
> > The quick brown fox\
> 
> >       jumps over the lazy dog
> 
> >
> 
> > …I am going to unfold as…
> 
> >
> 
> > The quick brown fox      jumps over the lazy dog
> 
> >
> 
> >
> 
> > Conversely, if I resolve this second case by stripping leading spaces
> 
> > I get…
> 
> >
> 
> > The quick brown foxjumps over the lazy dog
> 
> >
> 
> > So I have to fold as…
> 
> >
> 
> > The quick brown fox \
> 
> >       jumps over the lazy dog
> 
> >
> 
> > But this causes the first case to unfold as
> 
> >
> 
> > 1234567    9012345
> 
> >
> 
> > …i.e., with missing spaces.
> 
> >
> 
> > This is what caused the use of the second slash so…
> 
> >
> 
> > 1234567    \
> 
> > \    9012345
> 
> >
> 
> > …and…
> 
> >
> 
> > The quick brown fox\
> 
> >      \ jumps over the lazy dog
> 
> >
> 
> >
> 
> > So, my point is, if and only if we do not care about these “spaces on
> 
> > the fold” cases, we can operate with a single slash.
> 
> >
> 
> > Cheers,
> 
> > Adrian
> 
> >
> 
> > From: Joel Jaeggli
> > <joelja@bogus.com<mailto:joelja@bogus.com<mailto:joelja@bogus.com%3cmailto:joelja@bogus.com>>>
> 
> > Sent: 27 February 2019 06:31
> 
> > To: Adrian Farrel
> > <adrian@olddog.co.uk<mailto:adrian@olddog.co.uk<mailto:adrian@olddog.co.uk%3cmailto:adrian@olddog.co.uk>>>
> 
> > Cc: Kent Watsen
> > <kent+ietf@watsen.net<mailto:kent+ietf@watsen.net<mailto:kent+ietf@watsen.net%3cmailto:kent+ietf@watsen.net>>>;
> 
> > netmod@ietf.org<mailto:netmod@ietf.org<mailto:netmod@ietf.org%3cmailto:netmod@ietf.org>>
> 
> > Subject: Re: [netmod] artwork folding: dual support modes?
> 
> >
> 
> >
> 
> >
> 
> > On Feb 26, 2019, at 14:26, Adrian Farrel
> 
> > <adrian@olddog.co.uk<mailto:adrian@olddog.co.uk<mailto:adrian@olddog.co.uk%3cmailto:adrian@olddog.co.uk>>>
> > wrote:
> 
> >
> 
> > Hey.
> 
> >
> 
> > I’ve been having this discussion with Kent off-line, but thought it
> 
> > should come to the list.
> 
> >
> 
> > I don’t think it is a good idea to have two approaches. While it would
> 
> > be relatively easy to code for both approaches, it seems to add a
> 
> > degree of confusion if both have to be handled by the same code
> 
> > (consider deciding whether leading space characters are to be retained
> 
> > or not, something that can only be decided when the first non-space
> 
> > character is found), or by having different code for the two different
> 
> > cases.
> 
> >
> 
> > It doesn’t seem to me that both cases are needed. We can pick one or
> 
> > the other.
> 
> >
> 
> > A single slash has been used to wrap long lines in editors and shells
> 
> > for decades at this point.
> 
> >
> 
> > and yeah whatever it is one method seems better than two.
> 
> >
> 
> >
> 
> > And *if* we want to allow manual folding so that indents can be made
> 
> > to make the document more human-readable then we have to use a leading
> 
> > ‘\’ on continuation lines to show which spaces should be stripped and
> 
> > which retained.
> 
> >
> 
> > Cheers,
> 
> > Adrian
> 
> >
> 
> > From: netmod
> > <netmod-bounces@ietf.org<mailto:netmod-bounces@ietf.org<mailto:netmod-bounces@ietf.org%3cmailto:netmod-bounces@ietf.org>>>
> 
> > On Behalf Of Kent Watsen
> 
> > Sent: 25 February 2019 22:22
> 
> > To:
> > netmod@ietf.org<mailto:netmod@ietf.org<mailto:netmod@ietf.org%3cmailto:netmod@ietf.org>>
> 
> > Subject: [netmod] artwork folding: dual support modes?
> 
> >
> 
> >
> 
> > I had a chat with the tools team recently and, in the course of
> 
> > things, it was implied that the double backslash approach we have now
> 
> > was both surprising and non-intuitive.
> 
> >
> 
> > This got me thinking that we may have thrown the proverbial baby out
> 
> > with the bathwater.
> 
> > That is, currently we have a header that reads:
> 
> >
> 
> >
> 
> >   NOTE: '\\' line wrapping per BCP XX (RFC XXXX)
> 
> >
> 
> > So why not *also* support a header that reads (note the singe slash):
> 
> >
> 
> >
> 
> >   NOTE: '\' line wrapping per BCP XX (RFC XXXX)
> 
> >
> 
> > Whereby this second form only supports the folded line continuing on
> 
> > column 1 (no indents).
> 
> >
> 
> > Thoughts?
> 
> >
> 
> > Kent // contributor
> 
> >
> 
> >
> 
> > _______________________________________________
> 
> > netmod mailing list
> 
> > netmod@ietf.org<mailto:netmod@ietf.org<mailto:netmod@ietf.org%3cmailto:netmod@ietf.org>>
> 
> > https://www.ietf.org/mailman/listinfo/netmod
> 
> >