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

Robert Wilton <rwilton@cisco.com> Mon, 04 March 2019 13:39 UTC

Return-Path: <rwilton@cisco.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 06F27131138 for <netmod@ietfa.amsl.com>; Mon, 4 Mar 2019 05:39:43 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -14.501
X-Spam-Level:
X-Spam-Status: No, score=-14.501 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIMWL_WL_MED=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_HI=-5, SPF_PASS=-0.001, URIBL_BLOCKED=0.001, USER_IN_DEF_DKIM_WL=-7.5] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=cisco.com
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 DIyx-4tLogey for <netmod@ietfa.amsl.com>; Mon, 4 Mar 2019 05:39:39 -0800 (PST)
Received: from aer-iport-1.cisco.com (aer-iport-1.cisco.com [173.38.203.51]) (using TLSv1.2 with cipher DHE-RSA-SEED-SHA (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id DD74C13111C for <netmod@ietf.org>; Mon, 4 Mar 2019 05:39:38 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=cisco.com; i=@cisco.com; l=11772; q=dns/txt; s=iport; t=1551706778; x=1552916378; h=subject:to:cc:references:from:message-id:date: mime-version:in-reply-to:content-transfer-encoding; bh=tbvsbqGbVH9zzXc8fRK3qIAVVTYkAfMpQi6Kc2evVG8=; b=iJwD0pcM0IJVnW/UPqG3O0lVHo9kgcXSCpSN8N5dgKUpz6KtvxFVCC1Z qiX/1lSsk8HlqpGPDZ9YgTsbMmRLH5ZFnBs/Ky0UJmUYwWXd5v6nMXXD2 TRyNhOs3mVGgaAaDtj3qN5vRqDKmrbn8EkErFye0DITUpPjan+LVIUvvV I=;
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: =?us-ascii?q?A0AOAABDKX1c/xbLJq1kGQEBAQEBAQE?= =?us-ascii?q?BAQEBAQcBAQEBAQGBVAEBAQEBAQsBgneBAyeDSECIeYxSJY5pizMNGAuEA0Y?= =?us-ascii?q?ChEQ3Bg0BAQMBAQMBAwJtHAyFSgEBAQQBAQoXDwEFNgsMBAkCDgMEAQEBAgI?= =?us-ascii?q?jAwICJx8JCAYBDAYCAQEXgwcBgXUPjFKbZoEvhUSEYIELJAGLPoFAP4ERJwy?= =?us-ascii?q?CX4MeAQGEa4JXAooPAQMsAphmXQmHQ4srBhmCTIgsiCqKZIsYhzKBXSKBVjM?= =?us-ascii?q?aCBsVO4JsCYsDhT8/AzCRFQEB?=
X-IronPort-AV: E=Sophos;i="5.58,440,1544486400"; d="scan'208";a="10535220"
Received: from aer-iport-nat.cisco.com (HELO aer-core-4.cisco.com) ([173.38.203.22]) by aer-iport-1.cisco.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 04 Mar 2019 13:39:36 +0000
Received: from [10.63.23.61] (dhcp-ensft1-uk-vla370-10-63-23-61.cisco.com [10.63.23.61]) by aer-core-4.cisco.com (8.15.2/8.15.2) with ESMTP id x24Ddas1005109; Mon, 4 Mar 2019 13:39:36 GMT
To: Martin Bjorklund <mbj@tail-f.com>, adrian@olddog.co.uk
Cc: joelja@bogus.com, netmod@ietf.org
References: <8ddf74d483674c598e52ece716f70d0a@XCH-RCD-007.cisco.com> <20190304.124912.231750494593528236.mbj@tail-f.com> <0a8601d4d283$f13b2180$d3b16480$@olddog.co.uk> <20190304.141630.1246282625623673890.mbj@tail-f.com>
From: Robert Wilton <rwilton@cisco.com>
Message-ID: <ee2c5535-d801-3fbe-6387-710c09e0bfdb@cisco.com>
Date: Mon, 4 Mar 2019 13:39:36 +0000
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:60.0) Gecko/20100101 Thunderbird/60.5.2
MIME-Version: 1.0
In-Reply-To: <20190304.141630.1246282625623673890.mbj@tail-f.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
Content-Language: en-US
X-Outbound-SMTP-Client: 10.63.23.61, dhcp-ensft1-uk-vla370-10-63-23-61.cisco.com
X-Outbound-Node: aer-core-4.cisco.com
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/Y68Id9Mf6XsqKMv4FQanOYXiZm8>
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 13:39:43 -0000

On 04/03/2019 13:16, Martin Bjorklund wrote:
> "Adrian Farrel" <adrian@olddog.co.uk> wrote:
>> 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.
> Maybe b/c if we do, people will start to use it and write things
> like:
>
>             "location": "file://example.org/yang/packages/ietf-routing@v\
>     \1.3.1.json",
>             "description": "This package defines a small sample set of I\
>     \ETF routing YANG modules that could represent the set of IETF routi\
>     \ng functionality that a basic IP network device might be expected t\
>     \o support.",
>
>
> I know, it can easily be re-written into:
>
>             "location": "file://example.org/yang/packages\
>                               \/ietf-routing@v1.3.1.json",
>             "description": "This package defines a small sample set \
>                            \of IETF routing YANG modules that could \
>                            \represent the set of IETF routing \
>                            \functionality that a basic IP network \
>                            \device might be expected to support.",
>
> which is almost as readable as:
>
>             "location": "file://example.org/yang/packages\
>                                /ietf-routing@v1.3.1.json",
>             "description": "This package defines a small sample set \
>                             of IETF routing YANG modules that could \
>                             represent the set of IETF routing \
>                             functionality that a basic IP network \
>                             device might be expected to support.",

If I was fixing this by hand then I would probably get to this instead:

            "location": "file://example.org/yang/packages/ietf-routing@v\
    \1.3.1.json",
            "description": "This package defines a small sample set of \
    \IETF routing YANG modules that could represent the set of IETF \
    \routing functionality that a basic IP network device might be \
    \expected to support.",

I think that for the rest of that example (pages 34-37 of 
draft-rwilton-netmod-yang-packages-00), I think that the folding works 
pretty well, and the output is reasonably readable.

Thanks,
Rob


>
> /martin
>
>
>> 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