Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
> At least remove YANG from the example, and I also think that > auto-folding of tree diagrams should be strongly discouraged, so find > a better example for (b). Removed "YANG" and s/(e.g., tree diagrams)/, using a tool that doesn't observe line lengths. FWIW, pyang's --tree-line-length sometimes produces results worse than folded artwork. > Also remove YANG from 4.1 Done. > To further emphasize this, I think you should add YANG and tree diagrams as examples in section 4.2. You mean, as anti-examples? Kent // contributor ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
>> Now, to take it forward, I would like to constrain our efforts to >> solving the problem at hand. If our solution has wider applicability, >> that's great. But can we recognise that the overwhelming bulk of case >> we see today are in YANG documents and that's up to us to solve. > >That sounds like a good way forward; it calls for a number of changes, > tightening the applicability in sections 1, 2, 3 and 4 IMO. I'm unsure what the problem at hand is, but there is nothing NETMOD specific about this, and we (the IETF) wouldn't want each WG rolling their own solution. Also, note Martin's strong objection to seeing this being used for tree-diagrams and yang modules, so even less NETMOD specific... Adrian previously wrote "So it seemed that there would be value in defining how that artwork could be automatically wrapped allowing the authors to not worry about line wrapping." I agree, the ultimate goal would be to integrate this with `xml2rfc`, but it should be free to do so without regard for what kind of artwork it is, or from which WG it came from. Where in our rather liberal NETMOD charter sanctions this work? Kent // pick a hat ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
- Original Message - From: "Adrian Farrel" Sent: Saturday, September 29, 2018 12:51 AM All, the scope has become elastic over time. When we first wrote draft-wu-netmod-yang-xml-doc-conventions we were addressing a very specific problem: drafts and RFCs contain fragments (examples) of YANG (not the YANG modules themselves, but examples with actual values). Those fragments often extend over 73 columns and so have to be wrapped from presentation in the draft/RFC, but this creates invalid YANG. So some form of documentation convention is needed to indicate that the examples should not be treated as valid YANG and to help someone map them to valid YANG. Most documents that encountered this problem either dodged it (hoping a reviewer would not complain) or defined their own line wrapping rules. We thought it would be helpful to have a common approach and that was what we focused on. We also noticed that (probably for formatting reasons) the examples were often being produced using the construct in the source XML. So it seemed that there would be value in defining how that artwork could be automatically wrapped allowing the authors to not worry about line wrapping. We recognised that wrapping figures would probably be confusing and counter-productive so we recommend against it. And we made it an explicit thing not a default. Conversely, we noted that other "sample code" might benefit from wrapping, so we thought that should be in scope. Then we merged our efforts with Kent's. That's how we got here. Now, to take it forward, I would like to constrain our efforts to solving the problem at hand. If our solution has wider applicability, that's great. But can we recognise that the overwhelming bulk of case we see today are in YANG documents and that's up to us to solve. Adrian That sounds like a good way forward; it calls for a number of changes, tightening the applicability in sections 1, 2, 3 and 4 IMO. Tom Petch Thanks, Adrian > -Original Message- > From: netmod [mailto:netmod-boun...@ietf.org] On Behalf Of Kent Watsen > Sent: 28 September 2018 23:05 > To: tom petch > Cc: netmod@ietf.org > Subject: Re: [netmod] New Version Notification for draft-kwatsen-netmod- > artwork-folding-07.txt > > > Hi Tom, > > As contributor, I agree with you. The only reason that it is here > now is because draft-wu-netmod-yang-xml-doc-conventions did. > > As chair, let me discuss with my co-chairs. Meanwhile, would love > to hear others opinions. > > Kent > > > - Original Message - > > Kent > > Stepping back, I think that there is a problem of applicability. > > You have labelled this I-D draft..netmod.. and are discussing it on the > netmod WG list. Therefore I apply it to YANG I-D - to me, that is the > obvious connection - and the problem I keep seeing with YANG I-D is > lines too long - comment, description - in the YANG module so that is > the problem for which I want a solution (I see no problem with code > snippets). This has something to do with, I know not what, the > processing cycle of YANG modules, of the module being generated outside > the I-D/RFC process and then being inserted without the constraints that > the I-D/RFC process normally apply; I recall Benoit giving an > explanation. > > However, when I ignore the I-D name and the list we are on, and take the > text in isolation, then I wonder what are we doing here. This should be > on a different list, art perhaps or the main ietf list, since what you > are proposing has nothing to do with netmod, YANG or any of the topics > that this list discusses; rather it seeks to change the whole of the > IETF. > > So, put this up for adoption and I will oppose; this is outside our > remit. > > Tom Petch > > > > ___ > netmod mailing list > netmod@ietf.org > https://www.ietf.org/mailman/listinfo/netmod ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
+1, boiling ocean and making a common solution to address some various use cases beyond scope of netmod, YANG is not our intention. We have already tried to come up with complicate solutions (e.g., format aware folding)before and unfortunately it adds a lot of complexity and has a lot of limitations. -Qin -邮件原件- 发件人: netmod [mailto:netmod-boun...@ietf.org] 代表 Adrian Farrel 发送时间: 2018年9月29日 7:52 收件人: 'Kent Watsen'; 'tom petch' 抄送: netmod@ietf.org 主题: Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt All, the scope has become elastic over time. When we first wrote draft-wu-netmod-yang-xml-doc-conventions we were addressing a very specific problem: drafts and RFCs contain fragments (examples) of YANG (not the YANG modules themselves, but examples with actual values). Those fragments often extend over 73 columns and so have to be wrapped from presentation in the draft/RFC, but this creates invalid YANG. So some form of documentation convention is needed to indicate that the examples should not be treated as valid YANG and to help someone map them to valid YANG. Most documents that encountered this problem either dodged it (hoping a reviewer would not complain) or defined their own line wrapping rules. We thought it would be helpful to have a common approach and that was what we focused on. We also noticed that (probably for formatting reasons) the examples were often being produced using the construct in the source XML. So it seemed that there would be value in defining how that artwork could be automatically wrapped allowing the authors to not worry about line wrapping. We recognised that wrapping figures would probably be confusing and counter-productive so we recommend against it. And we made it an explicit thing not a default. Conversely, we noted that other "sample code" might benefit from wrapping, so we thought that should be in scope. Then we merged our efforts with Kent's. That's how we got here. Now, to take it forward, I would like to constrain our efforts to solving the problem at hand. If our solution has wider applicability, that's great. But can we recognise that the overwhelming bulk of case we see today are in YANG documents and that's up to us to solve. Thanks, Adrian > -Original Message- > From: netmod [mailto:netmod-boun...@ietf.org] On Behalf Of Kent Watsen > Sent: 28 September 2018 23:05 > To: tom petch > Cc: netmod@ietf.org > Subject: Re: [netmod] New Version Notification for > draft-kwatsen-netmod- artwork-folding-07.txt > > > Hi Tom, > > As contributor, I agree with you. The only reason that it is here now > is because draft-wu-netmod-yang-xml-doc-conventions did. > > As chair, let me discuss with my co-chairs. Meanwhile, would love to > hear others opinions. > > Kent > > > - Original Message - > > Kent > > Stepping back, I think that there is a problem of applicability. > > You have labelled this I-D draft..netmod.. and are discussing it on > the netmod WG list. Therefore I apply it to YANG I-D - to me, that is > the obvious connection - and the problem I keep seeing with YANG I-D > is lines too long - comment, description - in the YANG module so that > is the problem for which I want a solution (I see no problem with code > snippets). This has something to do with, I know not what, the > processing cycle of YANG modules, of the module being generated > outside the I-D/RFC process and then being inserted without the > constraints that the I-D/RFC process normally apply; I recall Benoit > giving an explanation. > > However, when I ignore the I-D name and the list we are on, and take > the text in isolation, then I wonder what are we doing here. This > should be on a different list, art perhaps or the main ietf list, > since what you are proposing has nothing to do with netmod, YANG or > any of the topics that this list discusses; rather it seeks to change > the whole of the IETF. > > So, put this up for adoption and I will oppose; this is outside our > remit. > > Tom Petch > > > > ___ > netmod mailing list > netmod@ietf.org > https://www.ietf.org/mailman/listinfo/netmod ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
All, the scope has become elastic over time. When we first wrote draft-wu-netmod-yang-xml-doc-conventions we were addressing a very specific problem: drafts and RFCs contain fragments (examples) of YANG (not the YANG modules themselves, but examples with actual values). Those fragments often extend over 73 columns and so have to be wrapped from presentation in the draft/RFC, but this creates invalid YANG. So some form of documentation convention is needed to indicate that the examples should not be treated as valid YANG and to help someone map them to valid YANG. Most documents that encountered this problem either dodged it (hoping a reviewer would not complain) or defined their own line wrapping rules. We thought it would be helpful to have a common approach and that was what we focused on. We also noticed that (probably for formatting reasons) the examples were often being produced using the construct in the source XML. So it seemed that there would be value in defining how that artwork could be automatically wrapped allowing the authors to not worry about line wrapping. We recognised that wrapping figures would probably be confusing and counter-productive so we recommend against it. And we made it an explicit thing not a default. Conversely, we noted that other "sample code" might benefit from wrapping, so we thought that should be in scope. Then we merged our efforts with Kent's. That's how we got here. Now, to take it forward, I would like to constrain our efforts to solving the problem at hand. If our solution has wider applicability, that's great. But can we recognise that the overwhelming bulk of case we see today are in YANG documents and that's up to us to solve. Thanks, Adrian > -Original Message- > From: netmod [mailto:netmod-boun...@ietf.org] On Behalf Of Kent Watsen > Sent: 28 September 2018 23:05 > To: tom petch > Cc: netmod@ietf.org > Subject: Re: [netmod] New Version Notification for draft-kwatsen-netmod- > artwork-folding-07.txt > > > Hi Tom, > > As contributor, I agree with you. The only reason that it is here > now is because draft-wu-netmod-yang-xml-doc-conventions did. > > As chair, let me discuss with my co-chairs. Meanwhile, would love > to hear others opinions. > > Kent > > > - Original Message - > > Kent > > Stepping back, I think that there is a problem of applicability. > > You have labelled this I-D draft..netmod.. and are discussing it on the > netmod WG list. Therefore I apply it to YANG I-D - to me, that is the > obvious connection - and the problem I keep seeing with YANG I-D is > lines too long - comment, description - in the YANG module so that is > the problem for which I want a solution (I see no problem with code > snippets). This has something to do with, I know not what, the > processing cycle of YANG modules, of the module being generated outside > the I-D/RFC process and then being inserted without the constraints that > the I-D/RFC process normally apply; I recall Benoit giving an > explanation. > > However, when I ignore the I-D name and the list we are on, and take the > text in isolation, then I wonder what are we doing here. This should be > on a different list, art perhaps or the main ietf list, since what you > are proposing has nothing to do with netmod, YANG or any of the topics > that this list discusses; rather it seeks to change the whole of the > IETF. > > So, put this up for adoption and I will oppose; this is outside our > remit. > > Tom Petch > > > > ___ > netmod mailing list > netmod@ietf.org > https://www.ietf.org/mailman/listinfo/netmod ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
Hi Tom, As contributor, I agree with you. The only reason that it is here now is because draft-wu-netmod-yang-xml-doc-conventions did. As chair, let me discuss with my co-chairs. Meanwhile, would love to hear others opinions. Kent - Original Message - Kent Stepping back, I think that there is a problem of applicability. You have labelled this I-D draft..netmod.. and are discussing it on the netmod WG list. Therefore I apply it to YANG I-D - to me, that is the obvious connection - and the problem I keep seeing with YANG I-D is lines too long - comment, description - in the YANG module so that is the problem for which I want a solution (I see no problem with code snippets). This has something to do with, I know not what, the processing cycle of YANG modules, of the module being generated outside the I-D/RFC process and then being inserted without the constraints that the I-D/RFC process normally apply; I recall Benoit giving an explanation. However, when I ignore the I-D name and the list we are on, and take the text in isolation, then I wonder what are we doing here. This should be on a different list, art perhaps or the main ietf list, since what you are proposing has nothing to do with netmod, YANG or any of the topics that this list discusses; rather it seeks to change the whole of the IETF. So, put this up for adoption and I will oppose; this is outside our remit. Tom Petch ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
Kent Stepping back, I think that there is a problem of applicability. You have labelled this I-D draft..netmod.. and are discussing it on the netmod WG list. Therefore I apply it to YANG I-D - to me, that is the obvious connection - and the problem I keep seeing with YANG I-D is lines too long - comment, description - in the YANG module so that is the problem for which I want a solution (I see no problem with code snippets). This has something to do with, I know not what, the processing cycle of YANG modules, of the module being generated outside the I-D/RFC process and then being inserted without the constraints that the I-D/RFC process normally apply; I recall Benoit giving an explanation. However, when I ignore the I-D name and the list we are on, and take the text in isolation, then I wonder what are we doing here. This should be on a different list, art perhaps or the main ietf list, since what you are proposing has nothing to do with netmod, YANG or any of the topics that this list discusses; rather it seeks to change the whole of the IETF. So, put this up for adoption and I will oppose; this is outside our remit. Tom Petch - Original Message - From: "Kent Watsen" To: "tom petch" Cc: Sent: Wednesday, September 26, 2018 9:08 PM > Hi Tom, > > > >> Good enough? > > > > No:-) The authors of YANG modules seem not to understand that it > > applies to them, or incorrectly use the tools that would apply > > were they correctly used. > > This seems to be a problem outside the scope of this draft. I was > thinking to strengthen Section 4.2 some, but this sentence really > seems to say it right: > >As such, it is RECOMMENDED that authors do as much as possible >within the selected format to avoid long lines. > > > > > OLD > > [RFC7994][RFC7994]sets out the requirements for plain-text RFCs and > > states that each line of an RFC (and hence of an Internet-Draft) must > > be limited to 72 characters followed by the character sequence that > > denotes an end-of-line (EOL). > > > > NEW > > [RFC7994]sets out the requirements for plain-text RFCs and > > states that each line of an RFC (and hence of an Internet-Draft) must > > be limited to 72 characters followed by the character sequence that > > denotes an end-of-line (EOL). This applies to all of an RFC, > > including, for example, the comments or description clauses in a YANG > > module, and to artwork. > > First, I'd recommend simplifying the last sentence to just "This applies > to all of an RFC, including any artwork.", but then it seems to step on > what the next paragraph says. Perhaps the next paragraph could be > simplified? - suggestions welcomed. > > > > Not sure why you have [RFC7994] twice. > > Fixed in my local copy. > > > PS: folded YANG-modules will break tooling (e.g., module validation) until > extraction tools (i.e., `xym`) are updated to be folding aware. Even after > this draft becomes an RFC, authors need to ensure that YANG modules are not > folded until such tools are updated. Other artwork (tree diagrams, instance > examples, etc.) being folded is not a problem, as no automated tooling acts > on them currently. > > > Kent // contributor > > > ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
Hi, Kent Watsen wrote: > Hi Tom, > > > >> Good enough? > > > > No:-) The authors of YANG modules seem not to understand that it > > applies to them, or incorrectly use the tools that would apply > > were they correctly used. > > This seems to be a problem outside the scope of this draft. I was > thinking to strengthen Section 4.2 some, but this sentence really > seems to say it right: > >As such, it is RECOMMENDED that authors do as much as possible >within the selected format to avoid long lines. I think you also should change the first paragraph in section 3.1: Automated folding of long lines is needed in order to support draft compilations that entail a) validation of source input files (e.g., YANG, XML, JSON, ABNF, ASN.1) and/or b) dynamic generation of output (e.g., tree diagrams) that are stitched into the final document to be submitted. At least remove YANG from the example, and I also think that auto-folding of tree diagrams should be strongly discouraged, so find a better example for (b). Also remove YANG from 4.1 To further emphasize this, I think you should add YANG and tree diagrams as examples in section 4.2. /martin > > > > OLD > > [RFC7994][RFC7994]sets out the requirements for plain-text RFCs and > > states that each line of an RFC (and hence of an Internet-Draft) must > > be limited to 72 characters followed by the character sequence that > > denotes an end-of-line (EOL). > > > > NEW > > [RFC7994]sets out the requirements for plain-text RFCs and > > states that each line of an RFC (and hence of an Internet-Draft) must > > be limited to 72 characters followed by the character sequence that > > denotes an end-of-line (EOL). This applies to all of an RFC, > > including, for example, the comments or description clauses in a YANG > > module, and to artwork. > > First, I'd recommend simplifying the last sentence to just "This applies > to all of an RFC, including any artwork.", but then it seems to step on > what the next paragraph says. Perhaps the next paragraph could be > simplified? - suggestions welcomed. > > > > Not sure why you have [RFC7994] twice. > > Fixed in my local copy. > > > PS: folded YANG-modules will break tooling (e.g., module validation) until > extraction tools (i.e., `xym`) are updated to be folding aware. Even after > this draft becomes an RFC, authors need to ensure that YANG modules are not > folded until such tools are updated. Other artwork (tree diagrams, instance > examples, etc.) being folded is not a problem, as no automated tooling acts > on them currently. > > > Kent // contributor > > > ___ > netmod mailing list > netmod@ietf.org > https://www.ietf.org/mailman/listinfo/netmod > > ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
Hi Tom, >> Good enough? > > No:-) The authors of YANG modules seem not to understand that it > applies to them, or incorrectly use the tools that would apply > were they correctly used. This seems to be a problem outside the scope of this draft. I was thinking to strengthen Section 4.2 some, but this sentence really seems to say it right: As such, it is RECOMMENDED that authors do as much as possible within the selected format to avoid long lines. > OLD > [RFC7994][RFC7994]sets out the requirements for plain-text RFCs and > states that each line of an RFC (and hence of an Internet-Draft) must > be limited to 72 characters followed by the character sequence that > denotes an end-of-line (EOL). > > NEW > [RFC7994]sets out the requirements for plain-text RFCs and > states that each line of an RFC (and hence of an Internet-Draft) must > be limited to 72 characters followed by the character sequence that > denotes an end-of-line (EOL). This applies to all of an RFC, > including, for example, the comments or description clauses in a YANG > module, and to artwork. First, I'd recommend simplifying the last sentence to just "This applies to all of an RFC, including any artwork.", but then it seems to step on what the next paragraph says. Perhaps the next paragraph could be simplified? - suggestions welcomed. > Not sure why you have [RFC7994] twice. Fixed in my local copy. PS: folded YANG-modules will break tooling (e.g., module validation) until extraction tools (i.e., `xym`) are updated to be folding aware. Even after this draft becomes an RFC, authors need to ensure that YANG modules are not folded until such tools are updated. Other artwork (tree diagrams, instance examples, etc.) being folded is not a problem, as no automated tooling acts on them currently. Kent // contributor ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
Original Message - From: "Kent Watsen" Sent: Monday, September 24, 2018 9:49 PM > Hi Tom, > > > I would like a paragraph in this I-D to the effect that editors should > > take care of this and that this phenomenon is nothing to do with the > > technique described here, a sort of non-Applicability statement so that > > we do not, in future, get too long lines as > > > > /* optical interface func needs to expand for Fiber Channel,\ > > \ SONET and SDH */ > > > > instead of turning them into > > > > /* optical interface func needs to expand > > for Fiber Channel, SONET and SDH */ > > Section 4.2 addresses this. In particular, the last line says: > > As such, it is RECOMMENDED that authors do as much as possible within > the selected format to avoid long lines. > > Good enough? No:-) The authors of YANG modules seem not to understand that it applies to them, or incorrectly use the tools that would apply were they correctly used. I had in mind something such as OLD [RFC7994][RFC7994]sets out the requirements for plain-text RFCs and states that each line of an RFC (and hence of an Internet-Draft) must be limited to 72 characters followed by the character sequence that denotes an end-of-line (EOL). NEW [RFC7994]sets out the requirements for plain-text RFCs and states that each line of an RFC (and hence of an Internet-Draft) must be limited to 72 characters followed by the character sequence that denotes an end-of-line (EOL). This applies to all of an RFC, including, for example, the comments or description clauses in a YANG module, and to artwork. Not sure why you have [RFC7994] twice. Tom Petch > Kent // contributor > ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
Hi Tom, > I would like a paragraph in this I-D to the effect that editors should > take care of this and that this phenomenon is nothing to do with the > technique described here, a sort of non-Applicability statement so that > we do not, in future, get too long lines as > > /* optical interface func needs to expand for Fiber Channel,\ > \ SONET and SDH */ > > instead of turning them into > > /* optical interface func needs to expand > for Fiber Channel, SONET and SDH */ Section 4.2 addresses this. In particular, the last line says: As such, it is RECOMMENDED that authors do as much as possible within the selected format to avoid long lines. Good enough? Kent // contributor ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
So, I'm slightly regretting bringing this up in the first place because
I'm not convinced it is worth the discussion time. Bob Harold's
solution is fine with me, and one that I was also considering
suggesting, so is the 'tabs are banned' solution currently in the draft.
I do strongly agree that using tabs to align genuine artwork (i.e.
diagrams and the like) is not a wise idea. However, the abstract from
the draft is:
This document introduces a simple and yet time-proven strategy for
handling long lines in artwork in drafts using a backslash ('\')
character where line-folding has occurred. The strategy works on any
text based artwork,*but is primarily intended for sample text and formatted
examples and code*, rather than for graphical artwork. The
approach produces consistent results regardless of the content and
uses a per-artwork header. The strategy is both self-documenting and
enables automated reconstitution of the original artwork.
So, this draft is intended is intended to cover text, formatted
examples, and code; and I'm not completely convinced that these will
never contains tabs, putting aside any discussion of what is best practice.
However, I'm happy to leave the final decision to the discretion of the
authors, or other WG members.
Rob
On 21/09/2018 12:48, tom petch wrote:
- Original Message -
From: "Bob Harold"
Sent: Wednesday, September 19, 2018 8:12 PM
On Tue, Sep 18, 2018 at 6:01 AM Adrian Farrel wrote:
Yeah :-Z
So my inclination is to say "tabs in artwork are evil" and move on.
Some folk like to use them when constructing text, but my suggestion
is
that they convert to spaces/LF before posting drafts.
If anyone wants to write another document tabs in json then, erm,
knock
yourselves out. But I would prefer to just exclude them from folding
at
this time.
Cheers,
Adrian
-Original Message-
From: netmod [mailto:netmod-boun...@ietf.org] On Behalf Of tom petch
Sent: 18 September 2018 10:54
- Original Message -
From: "Carsten Bormann"
Sent: Friday, September 14, 2018 12:14 PM
On Sep 14, 2018, at 13:05, Robert Wilton
wrote:
If all input files that we might ever want to fold and include
in an
RFC are guaranteed to never contain tabs then I agree with the
position
that they can just be rejected.
Yep.
But if there is some future file format that we want to fold
that
might contain tabs, then I wonder whether it would not be more
robust to
look at whether they could be handled in some way.
VT characters (colloquially tabs) should not be significant in any
file format designed in the last couple of decades (i.e., they
should be
replaceable by spaces). If they (or any other characters not
representable in RFCs) are, or preserving byte wise identity is
important, follow the lead of RFC 6716 and base64-encode.
This confuses me. This I-D references RFC7991 which clearly defines
tab
as 9, which RFC20 labels H(orizontal) T(ab). V(ertical) T(ab) is
11.
I would not expect VT to appear in any recent document but when it
does,
then replacing it by spaces would be wrong, IMHO. HT I do see, far
too
much of, because there is no metadata saying what the Horizontal Tab
settings should be and while a value of five is common, there are
RFC
where replacing tab characters with five spaces yields rubbish.
Tom Petch
Grüße, Carsten
The purpose of folding is to get all lines under a certain max width.
Tabs
were historically set every 8 characters, although terminals and editors
have allowed users to change them. Changes are typically to reduce them
to
4 or 2. I have not heard of anyone increasing them beyond 8. So for
purposes of max line length, 8 is the worst case. Then for folding,
count
tabs as filling to the next multiple of 8, (or worst case, assume a full
8)
and fold appropriately. This should unfold properly. (Do not attempt
to
replace tabs with spaces.) It won't always be what the author intended,
but it is the best that we can do. Better and simpler than trying to
enforce "no tabs allowed".
Bob
My experience of tabs is different, which is why I think that Adrian has
it right when he says
say "tabs in artwork are evil" and move on.
All the text processors I can recall had a default of tab meaning 5
spaces, never 2 or 4 or 8. And the prime use of tabs has been to
achieve vertical alignment in artwork, tables and such like, where the
tab settings might be
10 23 49 68
allowing a suitable amount of space for the different fields of the
table. (I see this usage going beyond text processing).
So, banish tabs; require the submitter to turn them into whatever they
mean by them first.
Tom Petch
--
Bob Harold
___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod
___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
Not about tabs! When I look at YANG modules, which I have done a bit of this year, I have two problems with line lengths, making it harder for me to review the I-Ds. One is the lengthy lines in the YANG tree diagram and that this I-D clearly addresses. The other is lines that are too long, for an RFC, in the YANG module, typically in description clauses and in comment lines. I don't know what the editors are doing to get such lines into an I-D but they do so I would like a paragraph in this I-D to the effect that editors should take care of this and that this phenomenon is nothing to do with the technique described here, a sort of non-Applicability statement so that we do not, in future, get too long lines as /* optical interface func needs to expand for Fiber Channel,\ \ SONET and SDH */ instead of turning them into /* optical interface func needs to expand for Fiber Channel, SONET and SDH */ I tried to explain this to an editor recently and had great difficulty in getting across that there was a problem, and this is not an isolated case; hence my wish to have something to point to about it. Tom Petch - Original Message - From: "t.petch" To: "Carsten Bormann" ; "Robert Wilton" Cc: Sent: Tuesday, September 18, 2018 10:53 AM > - Original Message - > From: "Carsten Bormann" > Sent: Friday, September 14, 2018 12:14 PM > > > On Sep 14, 2018, at 13:05, Robert Wilton > wrote: > > > > > > If all input files that we might ever want to fold and include in an > RFC are guaranteed to never contain tabs then I agree with the position > that they can just be rejected. > > > > Yep. > > > > > But if there is some future file format that we want to fold that > might contain tabs, then I wonder whether it would not be more robust to > look at whether they could be handled in some way. > > > > VT characters (colloquially tabs) should not be significant in any > file format designed in the last couple of decades (i.e., they should be > replaceable by spaces). If they (or any other characters not > representable in RFCs) are, or preserving byte wise identity is > important, follow the lead of RFC 6716 and base64-encode. > > This confuses me. This I-D references RFC7991 which clearly defines tab > as 9, which RFC20 labels H(orizontal) T(ab). V(ertical) T(ab) is 11. > > I would not expect VT to appear in any recent document but when it does, > then replacing it by spaces would be wrong, IMHO. HT I do see, far too > much of, because there is no metadata saying what the Horizontal Tab > settings should be and while a value of five is common, there are RFC > where replacing tab characters with five spaces yields rubbish. > > Tom Petch > > > > > > > > > > Grüße, Carsten > > > > ___ > > netmod mailing list > > netmod@ietf.org > > https://www.ietf.org/mailman/listinfo/netmod > > > ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
- Original Message - From: "Bob Harold" Sent: Wednesday, September 19, 2018 8:12 PM On Tue, Sep 18, 2018 at 6:01 AM Adrian Farrel wrote: > Yeah :-Z > > So my inclination is to say "tabs in artwork are evil" and move on. > Some folk like to use them when constructing text, but my suggestion is > that they convert to spaces/LF before posting drafts. > > If anyone wants to write another document tabs in json then, erm, knock > yourselves out. But I would prefer to just exclude them from folding at > this time. > > Cheers, > Adrian > > > -Original Message- > > From: netmod [mailto:netmod-boun...@ietf.org] On Behalf Of tom petch > > Sent: 18 September 2018 10:54 > > > > - Original Message - > > From: "Carsten Bormann" > > Sent: Friday, September 14, 2018 12:14 PM > > > > > On Sep 14, 2018, at 13:05, Robert Wilton > > wrote: > > > > > > > > If all input files that we might ever want to fold and include in an > > RFC are guaranteed to never contain tabs then I agree with the position > > that they can just be rejected. > > > > > > Yep. > > > > > > > But if there is some future file format that we want to fold that > > might contain tabs, then I wonder whether it would not be more robust to > > look at whether they could be handled in some way. > > > > > > VT characters (colloquially tabs) should not be significant in any > > file format designed in the last couple of decades (i.e., they should be > > replaceable by spaces). If they (or any other characters not > > representable in RFCs) are, or preserving byte wise identity is > > important, follow the lead of RFC 6716 and base64-encode. > > > > This confuses me. This I-D references RFC7991 which clearly defines tab > > as 9, which RFC20 labels H(orizontal) T(ab). V(ertical) T(ab) is 11. > > > > I would not expect VT to appear in any recent document but when it does, > > then replacing it by spaces would be wrong, IMHO. HT I do see, far too > > much of, because there is no metadata saying what the Horizontal Tab > > settings should be and while a value of five is common, there are RFC > > where replacing tab characters with five spaces yields rubbish. > > > > Tom Petch > > > > > Grüße, Carsten The purpose of folding is to get all lines under a certain max width. Tabs were historically set every 8 characters, although terminals and editors have allowed users to change them. Changes are typically to reduce them to 4 or 2. I have not heard of anyone increasing them beyond 8. So for purposes of max line length, 8 is the worst case. Then for folding, count tabs as filling to the next multiple of 8, (or worst case, assume a full 8) and fold appropriately. This should unfold properly. (Do not attempt to replace tabs with spaces.) It won't always be what the author intended, but it is the best that we can do. Better and simpler than trying to enforce "no tabs allowed". Bob My experience of tabs is different, which is why I think that Adrian has it right when he says say "tabs in artwork are evil" and move on. All the text processors I can recall had a default of tab meaning 5 spaces, never 2 or 4 or 8. And the prime use of tabs has been to achieve vertical alignment in artwork, tables and such like, where the tab settings might be 10 23 49 68 allowing a suitable amount of space for the different fields of the table. (I see this usage going beyond text processing). So, banish tabs; require the submitter to turn them into whatever they mean by them first. Tom Petch -- Bob Harold ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
On Tue, Sep 18, 2018 at 6:01 AM Adrian Farrel wrote: > Yeah :-Z > > So my inclination is to say "tabs in artwork are evil" and move on. > Some folk like to use them when constructing text, but my suggestion is > that they convert to spaces/LF before posting drafts. > > If anyone wants to write another document tabs in json then, erm, knock > yourselves out. But I would prefer to just exclude them from folding at > this time. > > Cheers, > Adrian > > > -Original Message- > > From: netmod [mailto:netmod-boun...@ietf.org] On Behalf Of tom petch > > Sent: 18 September 2018 10:54 > > To: Carsten Bormann; Robert Wilton > > Cc: netmod@ietf.org > > Subject: Re: [netmod] New Version Notification for draft-kwatsen-netmod- > > artwork-folding-07.txt > > > > - Original Message - > > From: "Carsten Bormann" > > Sent: Friday, September 14, 2018 12:14 PM > > > > > On Sep 14, 2018, at 13:05, Robert Wilton > > wrote: > > > > > > > > If all input files that we might ever want to fold and include in an > > RFC are guaranteed to never contain tabs then I agree with the position > > that they can just be rejected. > > > > > > Yep. > > > > > > > But if there is some future file format that we want to fold that > > might contain tabs, then I wonder whether it would not be more robust to > > look at whether they could be handled in some way. > > > > > > VT characters (colloquially tabs) should not be significant in any > > file format designed in the last couple of decades (i.e., they should be > > replaceable by spaces). If they (or any other characters not > > representable in RFCs) are, or preserving byte wise identity is > > important, follow the lead of RFC 6716 and base64-encode. > > > > This confuses me. This I-D references RFC7991 which clearly defines tab > > as 9, which RFC20 labels H(orizontal) T(ab). V(ertical) T(ab) is 11. > > > > I would not expect VT to appear in any recent document but when it does, > > then replacing it by spaces would be wrong, IMHO. HT I do see, far too > > much of, because there is no metadata saying what the Horizontal Tab > > settings should be and while a value of five is common, there are RFC > > where replacing tab characters with five spaces yields rubbish. > > > > Tom Petch > > > > > Grüße, Carsten > > The purpose of folding is to get all lines under a certain max width. Tabs were historically set every 8 characters, although terminals and editors have allowed users to change them. Changes are typically to reduce them to 4 or 2. I have not heard of anyone increasing them beyond 8. So for purposes of max line length, 8 is the worst case. Then for folding, count tabs as filling to the next multiple of 8, (or worst case, assume a full 8) and fold appropriately. This should unfold properly. (Do not attempt to replace tabs with spaces.) It won't always be what the author intended, but it is the best that we can do. Better and simpler than trying to enforce "no tabs allowed". -- Bob Harold ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
Yeah :-Z So my inclination is to say "tabs in artwork are evil" and move on. Some folk like to use them when constructing text, but my suggestion is that they convert to spaces/LF before posting drafts. If anyone wants to write another document tabs in json then, erm, knock yourselves out. But I would prefer to just exclude them from folding at this time. Cheers, Adrian > -Original Message- > From: netmod [mailto:netmod-boun...@ietf.org] On Behalf Of tom petch > Sent: 18 September 2018 10:54 > To: Carsten Bormann; Robert Wilton > Cc: netmod@ietf.org > Subject: Re: [netmod] New Version Notification for draft-kwatsen-netmod- > artwork-folding-07.txt > > - Original Message - > From: "Carsten Bormann" > Sent: Friday, September 14, 2018 12:14 PM > > > On Sep 14, 2018, at 13:05, Robert Wilton > wrote: > > > > > > If all input files that we might ever want to fold and include in an > RFC are guaranteed to never contain tabs then I agree with the position > that they can just be rejected. > > > > Yep. > > > > > But if there is some future file format that we want to fold that > might contain tabs, then I wonder whether it would not be more robust to > look at whether they could be handled in some way. > > > > VT characters (colloquially tabs) should not be significant in any > file format designed in the last couple of decades (i.e., they should be > replaceable by spaces). If they (or any other characters not > representable in RFCs) are, or preserving byte wise identity is > important, follow the lead of RFC 6716 and base64-encode. > > This confuses me. This I-D references RFC7991 which clearly defines tab > as 9, which RFC20 labels H(orizontal) T(ab). V(ertical) T(ab) is 11. > > I would not expect VT to appear in any recent document but when it does, > then replacing it by spaces would be wrong, IMHO. HT I do see, far too > much of, because there is no metadata saying what the Horizontal Tab > settings should be and while a value of five is common, there are RFC > where replacing tab characters with five spaces yields rubbish. > > Tom Petch > > > > > > > > > > Grüße, Carsten > > > > ___ > > netmod mailing list > > netmod@ietf.org > > https://www.ietf.org/mailman/listinfo/netmod > > > > ___ > netmod mailing list > netmod@ietf.org > https://www.ietf.org/mailman/listinfo/netmod ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
- Original Message - From: "Carsten Bormann" Sent: Friday, September 14, 2018 12:14 PM > On Sep 14, 2018, at 13:05, Robert Wilton wrote: > > > > If all input files that we might ever want to fold and include in an RFC are guaranteed to never contain tabs then I agree with the position that they can just be rejected. > > Yep. > > > But if there is some future file format that we want to fold that might contain tabs, then I wonder whether it would not be more robust to look at whether they could be handled in some way. > > VT characters (colloquially tabs) should not be significant in any file format designed in the last couple of decades (i.e., they should be replaceable by spaces). If they (or any other characters not representable in RFCs) are, or preserving byte wise identity is important, follow the lead of RFC 6716 and base64-encode. This confuses me. This I-D references RFC7991 which clearly defines tab as 9, which RFC20 labels H(orizontal) T(ab). V(ertical) T(ab) is 11. I would not expect VT to appear in any recent document but when it does, then replacing it by spaces would be wrong, IMHO. HT I do see, far too much of, because there is no metadata saying what the Horizontal Tab settings should be and while a value of five is common, there are RFC where replacing tab characters with five spaces yields rubbish. Tom Petch > > Grüße, Carsten > > ___ > netmod mailing list > netmod@ietf.org > https://www.ietf.org/mailman/listinfo/netmod > ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
On Sep 14, 2018, at 13:05, Robert Wilton wrote: > > If all input files that we might ever want to fold and include in an RFC are > guaranteed to never contain tabs then I agree with the position that they can > just be rejected. Yep. > But if there is some future file format that we want to fold that might > contain tabs, then I wonder whether it would not be more robust to look at > whether they could be handled in some way. VT characters (colloquially tabs) should not be significant in any file format designed in the last couple of decades (i.e., they should be replaceable by spaces). If they (or any other characters not representable in RFCs) are, or preserving byte wise identity is important, follow the lead of RFC 6716 and base64-encode. Grüße, Carsten ___ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
On 13/09/2018 22:43, Joel Jaeggli wrote:
On Sep 10, 2018, at 12:51 AM, Robert Wilton
<mailto:rwilton=40cisco@dmarc.ietf.org>> wrote:
I've read -07, and would also support an WG adoption call for this
draft. In fact, I think that it would be quite good if we can move
this document through to WG LC fairly expediently as well.
A couple of minor review comments:
Introduction: RFC7994 reference listed twice.
Rather than banning tabs, another option would to be convert them (of
course, the question is then whether a tab is 2, 4, or 8 spaces ...),
although assuming 4 spaces seems reasonable, and could be controlled
via an input parameter.
This does seem like the sort of classical place to have argument about
the size of a tab. To me the 7991 position is compelling. The onus is
the formatter to use an element which is not ambiguous.
I would rather not get involved in any argument/discussion/debate on how
many spaces a tab should represent, or even whether they should be used.
If all input files that we might ever want to fold and include in an RFC
are guaranteed to never contain tabs then I agree with the position that
they can just be rejected.
But if there is some future file format that we want to fold that might
contain tabs, then I wonder whether it would not be more robust to look
at whether they could be handled in some way.
Thanks,
Rob
It’s not really anyones business that I have
|set tabstop=2 shiftwidth=2 expandtab|
In my vimrc nor should it be.
Thanks,
Rob
On 08/09/2018 13:39, Adrian Farrel wrote:
Speaking as a co-author, I agree with Kent that this version is
ready for the WG
to pick up.
I think that discussions at f2f meetings indicated that there was
interest in
the WG in addressing this issue, and after much back and forth, the
authors have
come together with an approach that they agree on and it
incorporates some
suggestions made in Montreal.
Thanks,
Adrian
-Original Message-
From: netmod [mailto:netmod-boun...@ietf.org] On Behalf Of Kent Watsen
Sent: 07 September 2018 22:59
To: netmod@ietf.org <mailto:netmod@ietf.org>
Subject: [netmod] FW: New Version Notification for
draft-kwatsen-netmod-
artwork-folding-07.txt
An update to the "artwork-folding" draft has been posted.
- the solution is now using the "/.../" format.
- the included script has been updated as well.
We believe that this draft is ready for an adoption poll.
Kent (and Adrian and Qin) // authors
-Original Message-
A new version of I-D, draft-kwatsen-netmod-artwork-folding-07.txt
has been successfully submitted by Kent Watsen and posted to the
IETF repository.
Name:draft-kwatsen-netmod-artwork-folding
Revision:07
Title:Handling Long Lines in Artwork in Internet-Drafts and
RFCs
Document date:2018-09-05
Group:Individual Submission
Pages:16
URL: https://www.ietf.org/id/draft-kwatsen-netmod-artwork-folding-
07.txt
Status: https://datatracker.ietf.org/doc/draft-kwatsen-netmod-artwork-
folding/
Htmlized:
https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-
07
Htmlized:
https://datatracker.ietf.org/doc/html/draft-kwatsen-netmod-
artwork-folding
Diff:
https://www.ietf.org/rfcdiff?url2=draft-kwatsen-netmod-artwork-
folding-07
Abstract:
This document introduces a simple and yet time-proven strategy for
handling long lines in artwork in drafts using a backslash ('\')
character where line-folding has occurred. The strategy works
on any
text based artwork, but is primarily intended for sample text and
formatted examples and code, rather than for graphical artwork. The
approach produces consistent results regardless of the content and
uses a per-artwork header. The strategy is both
self-documenting and
enables automated reconstitution of the original artwork.
Please note that it may take a couple of minutes from the time of
submission
until the htmlized version and diff are available at tools.ietf.org.
The IETF Secretariat
___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod
___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod
.
___
netmod mailing list
netmod@ietf.org <mailto:netmod@ietf.org>
https://www.ietf.org/mailman/listinfo/netmod
___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod
Re: [netmod] New Version Notification for draft-kwatsen-netmod-artwork-folding-07.txt
> On Sep 10, 2018, at 12:51 AM, Robert Wilton
> wrote:
>
> I've read -07, and would also support an WG adoption call for this draft. In
> fact, I think that it would be quite good if we can move this document
> through to WG LC fairly expediently as well.
>
> A couple of minor review comments:
>
> Introduction: RFC7994 reference listed twice.
>
> Rather than banning tabs, another option would to be convert them (of course,
> the question is then whether a tab is 2, 4, or 8 spaces ...), although
> assuming 4 spaces seems reasonable, and could be controlled via an input
> parameter.
This does seem like the sort of classical place to have argument about the size
of a tab. To me the 7991 position is compelling. The onus is the formatter to
use an element which is not ambiguous.
It’s not really anyones business that I have
set tabstop=2 shiftwidth=2 expandtab
In my vimrc nor should it be.
> Thanks,
> Rob
>
>
> On 08/09/2018 13:39, Adrian Farrel wrote:
>> Speaking as a co-author, I agree with Kent that this version is ready for
>> the WG
>> to pick up.
>>
>> I think that discussions at f2f meetings indicated that there was interest in
>> the WG in addressing this issue, and after much back and forth, the authors
>> have
>> come together with an approach that they agree on and it incorporates some
>> suggestions made in Montreal.
>>
>> Thanks,
>> Adrian
>>
>>> -Original Message-
>>> From: netmod [mailto:netmod-boun...@ietf.org] On Behalf Of Kent Watsen
>>> Sent: 07 September 2018 22:59
>>> To: netmod@ietf.org
>>> Subject: [netmod] FW: New Version Notification for draft-kwatsen-netmod-
>>> artwork-folding-07.txt
>>>
>>>
>>> An update to the "artwork-folding" draft has been posted.
>>> - the solution is now using the "/.../" format.
>>> - the included script has been updated as well.
>>>
>>> We believe that this draft is ready for an adoption poll.
>>>
>>> Kent (and Adrian and Qin) // authors
>>>
>>>
>>> -Original Message-
>>>
>>> A new version of I-D, draft-kwatsen-netmod-artwork-folding-07.txt
>>> has been successfully submitted by Kent Watsen and posted to the
>>> IETF repository.
>>>
>>> Name: draft-kwatsen-netmod-artwork-folding
>>> Revision: 07
>>> Title: Handling Long Lines in Artwork in Internet-Drafts and
>> RFCs
>>> Document date: 2018-09-05
>>> Group: Individual Submission
>>> Pages: 16
>>> URL:
>>> https://www.ietf.org/id/draft-kwatsen-netmod-artwork-folding-
>>> 07.txt
>>> Status:
>>> https://datatracker.ietf.org/doc/draft-kwatsen-netmod-artwork-
>>> folding/
>>> Htmlized:
>> https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-
>>> 07
>>> Htmlized: https://datatracker.ietf.org/doc/html/draft-kwatsen-netmod-
>>> artwork-folding
>>> Diff:
>> https://www.ietf.org/rfcdiff?url2=draft-kwatsen-netmod-artwork-
>>> folding-07
>>>
>>> Abstract:
>>>This document introduces a simple and yet time-proven strategy for
>>>handling long lines in artwork in drafts using a backslash ('\')
>>>character where line-folding has occurred. The strategy works on any
>>>text based artwork, but is primarily intended for sample text and
>>>formatted examples and code, rather than for graphical artwork. The
>>>approach produces consistent results regardless of the content and
>>>uses a per-artwork header. The strategy is both self-documenting and
>>>enables automated reconstitution of the original artwork.
>>>
>>>
>>>
>>>
>>> Please note that it may take a couple of minutes from the time of submission
>>> until the htmlized version and diff are available at tools.ietf.org.
>>>
>>> The IETF Secretariat
>>>
>>>
>>>
>>> ___
>>> netmod mailing list
>>> netmod@ietf.org
>>> https://www.ietf.org/mailman/listinfo/netmod
>> ___
>> netmod mailing list
>> netmod@ietf.org
>> https://www.ietf.org/mailman/listinfo/netmod
>> .
>>
>
> ___
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod
>
signature.asc
Description: Message signed with OpenPGP
___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod
