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

"Adrian Farrel" <adrian@olddog.co.uk> Mon, 04 March 2019 12:15 UTC

Return-Path: <adrian@olddog.co.uk>
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 2DDE3130F3E for <netmod@ietfa.amsl.com>; Mon, 4 Mar 2019 04:15:44 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.599
X-Spam-Level:
X-Spam-Status: No, score=-2.599 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7, 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 Rh63U84xZ8gM for <netmod@ietfa.amsl.com>; Mon, 4 Mar 2019 04:15:40 -0800 (PST)
Received: from mta7.iomartmail.com (mta7.iomartmail.com [62.128.193.157]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 50930129B88 for <netmod@ietf.org>; Mon, 4 Mar 2019 04:15:40 -0800 (PST)
Received: from vs1.iomartmail.com (vs1.iomartmail.com [10.12.10.121]) by mta7.iomartmail.com (8.14.4/8.14.4) with ESMTP id x24CFOA9021980; Mon, 4 Mar 2019 12:15:24 GMT
Received: from vs1.iomartmail.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 3C00222044; Mon, 4 Mar 2019 12:15:24 +0000 (GMT)
Received: from asmtp2.iomartmail.com (unknown [10.12.10.249]) by vs1.iomartmail.com (Postfix) with ESMTPS id 301B82203C; Mon, 4 Mar 2019 12:15:24 +0000 (GMT)
Received: from LAPTOPK7AS653V ([87.112.237.8]) (authenticated bits=0) by asmtp2.iomartmail.com (8.14.4/8.14.4) with ESMTP id x24CFMEB020440 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Mon, 4 Mar 2019 12:15:23 GMT
Reply-To: <adrian@olddog.co.uk>
From: "Adrian Farrel" <adrian@olddog.co.uk>
To: "'Martin Bjorklund'" <mbj@tail-f.com>, <rwilton@cisco.com>
Cc: <joelja@bogus.com>, <netmod@ietf.org>
References: <3af58c925ad74fbfaaea299877bf992d@XCH-RCD-007.cisco.com> <20190304.094006.527512831015675938.mbj@tail-f.com> <8ddf74d483674c598e52ece716f70d0a@XCH-RCD-007.cisco.com> <20190304.124912.231750494593528236.mbj@tail-f.com>
In-Reply-To: <20190304.124912.231750494593528236.mbj@tail-f.com>
Date: Mon, 4 Mar 2019 12:15:21 -0000
Organization: Old Dog Consulting
Message-ID: <0a8601d4d283$f13b2180$d3b16480$@olddog.co.uk>
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
X-Mailer: Microsoft Outlook 16.0
Thread-Index: AQMHu3WhtJkAHXxS/VctXzN5BZqX3AFAA0wXAiaXwNYCd9eZJ6NmmLQg
Content-Language: en-gb
X-Originating-IP: 87.112.237.8
X-Thinkmail-Auth: adrian@olddog.co.uk
X-TM-AS-GCONF: 00
X-TM-AS-Product-Ver: IMSVA-9.0.0.1623-8.2.0.1013-24468.007
X-TM-AS-Result: No--24.874-10.0-31-10
X-imss-scan-details: No--24.874-10.0-31-10
X-TMASE-Version: IMSVA-9.0.0.1623-8.2.1013-24468.007
X-TMASE-Result: 10--24.874200-10.000000
X-TMASE-MatchedRID: IeZYkn8zfFrxIbpQ8BhdbBrhN1MlBxtXlavqJJda2A9tw+n+iKWyyDUi 2rTIOxGGHj9B9PDoFzY5OiEBrpf5GIn6k1037kFFbMGKOuLn5FW/yN2q8U674pMxNpDOG+h6MoL 75Np9g5Hofwk6BENqt4SntUu3UyDoN6IarY2VLsXLXx7n52sqBtvZ+Av1leBDtXl9IxEPXOpL2N LsmEw1pour1HfBNMzymoZiR6+1rnpJJDuM6qazTp+EzsRrGT9IAlw1lJDBMtbnlNKhb+fAftzDh HEbpyKJL2xKyO2nWckXrDym7KLmMXmg0CBYPBomVP9jNEQH04qISipZVWCNK3rLpEOVMxqCIQ+L dPSbXXfjwrdDzo+b5CLwFvmVycNTyttJ+hdquL10+657dxGJGEopYlyHMD9xFdX7UGTqqi88pP1 yRKiQEKV1uIiqSYhttNBc5cDzl52kOIY39zkh2INoF/xJo8tUGK57kZ/2mal5QxmV/TDSy+SRrT Xa9QISP0hUFl/RZU7F6+8r30DovKNvJJBiq11aeqVpqRXfKN798SfleimUWgFbHA9TqNLQzMTXS bS0boyUdP0yWQMv8Q0+N8q2MiER3yonOZkt7j1+H/Q3vgskAlNYbkWQyPvqrnXbZcNeApMqbQiL HBNHpvdblpHZADIqZb0EtRCZTyjD6egsHKBhOPVFR4sC8dPyh8Ytn75ClDNq4coTktrGXwO6X04 dSW3WmlpTJ7lBraGT9qSqoOimPOWQ0Aaj99laj5hLPCX3ZdPj5lyuq8IOQSvkvrkNi/adupCV1T w0TOmq/r7ujTTNh0vG5ZTMMcYZhTfqy01DegSeAiCmPx4NwFkMvWAuahr8m5N2YHMD0b+BikYCu AJJ8gtuKBGekqUpPjKoPgsq7cA=
X-TMASE-SNAP-Result: 1.821001.0001-0-1-12:0,22:0,33:0,34:0-0
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/xS-XbucQG0jCPlt9HiFtBaM9a-w>
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 12:15:44 -0000

We can go round and round 😊

How do I fold
  foo bar baz         buzz
so that it can be unfolded?

Clearly a possibility is
  foo bar baz         \
  buzz

But what if the line length would break in the white space?
You could solve it as 
  foo bar \
  baz         buzz
which requires slightly more complex folding.

Actually, this case arises more often than you might think when the line length would cause a fold before a single space.
Thus, if the line length is 11
foo bar baz buzz
..would fold as...
foo bar baz\
 buzz
...and unfold as...
foo bar bazbuzz
...if leading spaces are stripped.

And if leading spaces are not stripped then we cannot handle manual padding for reasons of visual formatting. For example...
foo bar baz\
       buzz

Personally, I am *really* struggling to understand why we cannot use the two-slash approach only. 

Cheers,
Adrian


-----Original Message-----
From: Martin Bjorklund <mbj@tail-f.com> 
Sent: 04 March 2019 11:49
To: 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> 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
> 
> >