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

[Martin Bjorklund <[e-mail]>]

Robert Wilton <[e-mail]> wrote:
> 
> On 04/03/2019 11:49, Martin Bjorklund wrote:
> > "Rob Wilton (rwilton)" <[e-mail]> 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.
> 
> But this does give a different meaning to a well used notation, that
> may well cause surprise and confusion.
> 
> 
> >    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
> 
> This one.  The counter example:

But note that figures in RFCs are normally indented with 3 spaces
(they _can_ be outdented, if the lines are long enough).

> 
>   foo bar baz\
>   buzz
> 
> Do you think that this is:
> 
>   foo bar bazbuzz

This one.

> 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.
> 
> No line break is added.  It was performing a line split on "container
> test".

I meant, don't use tools to do folding (or use a smart tool).

> > 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.
> 
> The choice of solution seems to make it quite restricted where it can
> be validly used.  I.e. it is only safe to use to fold documents where
> whitespace has no significance, and can be arbitrarily removed from
> the folded object without changing the document's meaning.
> 
> I think that this would mean that the folding mechanism isn't safe on
> either XML or JSON documents (since whitespace is significant,
> e.g. within a string).

For the use case that I envision, i.e., manually added \'s, I don't
think this is an issue.  It might be that we're trying to solve
different problems - I would like a solution that is intuitive for the
reader and has a minimal amount of noise, but I think that some others
think it is more important that tools can be used to automate the
folding process.

> There seems to be a ever growing list of things that we can't safely
> use this form of artwork folding on.  Are there are any examples of
> stuff that we can safely use it on? ;-)


Just to be clear: my preference is for a single \ as described above,
but I am ok with the solution in the current draft (an additional \ on
the next line).



/martin




> 
> Thanks,
> Rob
> 
> 
> >
> >
> > /martin
> >
> >
> >
> >
> >
> >>
> >>
> >> Thanks,
> >> Rob
> >>
> >>
> >>
> >>
> >>
> >> -----Original Message-----
> >> From: Martin Bjorklund <[e-mail]>
> >> Sent: 04 March 2019 08:40
> >> To: Rob Wilton (rwilton) <[e-mail]>
> >> Cc: [e-mail]; [e-mail]; [e-mail]
> >> Subject: Re: [netmod] artwork folding: dual support modes?
> >>
> >>
> >>
> >> "Rob Wilton (rwilton)" <[e-mail]<mailto:[e-mail]>>
> >> 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 <[e-mail]<mailto:[e-mail]>>
> >>> On Behalf Of Adrian Farrel
> >>> Sent: 27 February 2019 09:41
> >>> To: 'Joel Jaeggli' <[e-mail]<mailto:[e-mail]>>
> >>> Cc: [e-mail]<mailto:[e-mail]>
> >>> 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
> >>> <[e-mail]<mailto:[e-mail]<mailto:[e-mail]%3cmailto:[e-mail]>>>
> >>> Sent: 27 February 2019 06:31
> >>> To: Adrian Farrel
> >>> <[e-mail]<mailto:[e-mail]<mailto:[e-mail]%3cmailto:[e-mail]>>>
> >>> Cc: Kent Watsen
> >>> <[e-mail]<mailto:[e-mail]<mailto:[e-mail]%3cmailto:[e-mail]>>>;
> >>> [e-mail]<mailto:[e-mail]<mailto:[e-mail]%3cmailto:[e-mail]>>
> >>> Subject: Re: [netmod] artwork folding: dual support modes?
> >>> On Feb 26, 2019, at 14:26, Adrian Farrel
> >>> <[e-mail]<mailto:[e-mail]<mailto:[e-mail]%3cmailto:[e-mail]>>>
> >>> 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
> >>> <[e-mail]<mailto:[e-mail]<mailto:[e-mail]%3cmailto:[e-mail]>>>
> >>> On Behalf Of Kent Watsen
> >>> Sent: 25 February 2019 22:22
> >>> To:
> >>> [e-mail]<mailto:[e-mail]<mailto:[e-mail]%3cmailto:[e-mail]>>
> >>> 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
> >>> [e-mail]<mailto:[e-mail]<mailto:[e-mail]%3cmailto:[e-mail]>>
> >>> https://www.ietf.org/mailman/listinfo/netmod
>