On 04/03/2019 13:16, Martin Bjorklund wrote:
"Adrian Farrel" <[email protected]> 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\
\/[email protected]",
"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\
/[email protected]",
"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 <[email protected]>
Sent: 04 March 2019 11:49
To: [email protected]
Cc: [email protected]; [email protected]; [email protected]
Subject: Re: [netmod] artwork folding: dual support modes?
"Rob Wilton (rwilton)" <[email protected]> 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 <[email protected]>
Sent: 04 March 2019 08:40
To: Rob Wilton (rwilton) <[email protected]>
Cc: [email protected]; [email protected]; [email protected]
Subject: Re: [netmod] artwork folding: dual support modes?
"Rob Wilton (rwilton)" <[email protected]<mailto:[email protected]>>
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 <[email protected]<mailto:[email protected]>>
On Behalf Of Adrian Farrel
Sent: 27 February 2019 09:41
To: 'Joel Jaeggli' <[email protected]<mailto:[email protected]>>
Cc: [email protected]<mailto:[email protected]>
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
<[email protected]<mailto:[email protected]<mailto:[email protected]%3cmailto:[email protected]>>>
Sent: 27 February 2019 06:31
To: Adrian Farrel
<[email protected]<mailto:[email protected]<mailto:[email protected]%3cmailto:[email protected]>>>
Cc: Kent Watsen
<[email protected]<mailto:[email protected]<mailto:[email protected]%3cmailto:[email protected]>>>;
[email protected]<mailto:[email protected]<mailto:[email protected]%3cmailto:[email protected]>>
Subject: Re: [netmod] artwork folding: dual support modes?
On Feb 26, 2019, at 14:26, Adrian Farrel
<[email protected]<mailto:[email protected]<mailto:[email protected]%3cmailto:[email protected]>>>
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
<[email protected]<mailto:[email protected]<mailto:[email protected]%3cmailto:[email protected]>>>
On Behalf Of Kent Watsen
Sent: 25 February 2019 22:22
To:
[email protected]<mailto:[email protected]<mailto:[email protected]%3cmailto:[email protected]>>
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
[email protected]<mailto:[email protected]<mailto:[email protected]%3cmailto:[email protected]>>
https://www.ietf.org/mailman/listinfo/netmod
_______________________________________________
netmod mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/netmod
