Kent Watsen <[email protected]> wrote: > > Hi Martin, > > First, I just posted -05 to address the missing artwork: > https://tools.ietf.org/html/draft-kwatsen-netmod-artwork-folding-05.
Thanks! (The exmaples with just a string of '\' are highy confusing. Unclear what they try to tell me... probably that the alg is much more difficult than I originally thought ;-) > See below for more comments. > > Kent // contributor > > > ===== original message ===== > > > Hi, > > > > I support this work. See below for some comments. > > > > Qin Wu <[email protected]> wrote: > >> Dear WG, > >> > >> As you may recall I presented yang-xml-doc-conventions in London. > >> There was strong support for trying to solve the problem and mixed > >> views on the solution, other than that we should do it fast. In the > >> meanwhile, Kent submitted artwork-folding as an alternative solution. > >> > >> The authors of the two drafts decided to combine efforts. After > >> several internal iterations on both drafts, the drafts were becoming > >> more alike than different(both support auto wrapping or auto folding). > >> The artwork-folding draft was selected as a preferred offering basis > >> (i.e., draft-kwatsen-netmod-artwork-folding-04) to the working group > >> to consider for adoption. > >> > >> The primary feature differences remained are: > >> - all folded lines continue of column 0 without two character > >> indentation, i.e., whether auto indentation should be supported. > > > > I really liked the flexible indentation in the other draft. I suggest > > it is added to this draft. It enhances readability (if the author > > wants it). > > Variable indentation, when the folded-line starts on same column as > the previous line, looks nice. The current yang-xml-doc-conventions > draft has a fixed two-space indent, which would only look nice sometimes > while introducing a surprise factor other times. Hmm, I thought it had variable-length indentation. > Variable indent introduces significant complexity; at least, it's beyond > what can be accomplished by a `sed` one-liner, such as in the current > draft. A fixed two-space indent is possible (easy), but zero-space > indent is more common (less surprising) than a fixed indent. I like the algorithm in the other draft better - it had variable placement of the line break ("\\n" sequence), and variable indentation. Note that your proposed format is just a special case of the format in the other draft, so you can still use your "one-liner" sed to produce your result. > >> - handle two special case on backslash and space at the end of broken > >> line in yang-xml-doc-conventions. > >> - propose to use <WRAPPED TEXT BEGIN><WRAPPED TEXT END> to extract > >> artwork from I-Ds. > > > > The artwork draft proposes only a header, which means that it is not > > quite clear where the artwork ends. > > Interesting point, but I think that artwork-framing is a different problem > from artwork-folding. If the goal is to support extracting artwork from > txt-based RFC scripts, regardless if the artwork is folded or not, then we > could level-up this draft to that role, while still supporting folding. > > If we were to add a footer, maybe something like this: > > ===padding=== End Folding per BCP XX (RFC XXXX) ===padding=== > > where the "padding" fills in '=' characters until the max-line width is > reached (same as how the header is done). Ok. > >> In the artwork draft, section 5.3, you write: > >> > >> This line is self-describing in > >> three ways: use of '\' character, identification of BCP/RFC, and > >> identification of what the maximum line length is for the artwork. > >> > > I was confused about this maximum line length; it seems you define the > > maximum line length ot be 53, but that seems too limiting, and indeed > > in the example in 5.4 the max line length is 69. (BTW, the example is > > missing in the draft, as is the shell script in Appendix A). In any > > case, I don't see how the header identifies the max line length. > > The draft says that the *minimal* header string is 53-characters). We > can make it less if needed, but it involves needing to fold the header > itself, which could become messy. Thoughts? > > Per the line just before the one quoted above, this line is '=' padded > on both sides until reaching the max value. Apparently, this isn't > clear enough in the text, or do you think it's okay now? The draft says: The header is two lines long. The first line is the following 53-character string This is what made me confused. I now understand that the idea is to pad with '='. But if we adopt the algorithm in the other draft, we don't need a maximum line length like this. /martin > For what it's worth, I originally had the actually fold-column > (e.g., 69) printed in the header, but it was realized that it was > noise to the reader (humans don't care about the fold column number), > whereas padding the line out provides visually meaningful information > (e.g., one can hover the cursor over the end and then scroll the > document to find all the folds). > > > > > Also, in section 5.2, the first sentence is: > > > > Scan the artwork to see if any line exceeds the desired maximum. > > > > But what is the desired maximum? I assume that the idea is that the > > author first selects a desired max? Maybe add a line that explains > > this, and again write that 69 is a reasonable value for use in I-Ds > > and RFCs. > > Right, the idea is that the author has a target fold-column in mind. > It's an input parameter to the script in the appendix. The max value > defaults to 69. > > I added the following sentence before the "scan" line above: > > Determine the desired maximum line length from input. If no > value is explicitly specified, the value "69" SHOULD be used. > > > > > /martin > > Kent // contributor > > > _______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
