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

[Martin Bjorklund <[e-mail]>]

"Adrian Farrel" <[e-mail]> 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\
                             \/[e-mail]",
           "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\
                              /[e-mail]",
           "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.",


/martin


> 
> Cheers,
> Adrian
> 
> 
> -----Original Message-----
> From: Martin Bjorklund <[e-mail]> 
> Sent: 04 March 2019 11:49
> To: [e-mail]
> Cc: [e-mail]; [e-mail]; [e-mail]
> Subject: Re: [netmod] artwork folding: dual support modes?
> 
> "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.  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 <[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
> > 
> > >
>