Editorial convention: Semantic line breaks

[emlun]

Semantic line breaks is an editorial convention that may facilitate more efficient work on the text, while making no difference to the rendered output.

Currently, the WebAuthn spec source is a mix of at least 3 styles of line breaks:

• No line breaks: a whole paragraph of text may be a single line in the source. Example in spec
• Hard-wrapped text: add a line break before each word that would extend past some particular column width. The column limit also varies throughout the document. Example in spec
• Semantic line breaks: add line breaks at semantically meaningful points, such as after punctuation, before subordinate clauses, etc. Example in spec

Of the three, I find that semantic line breaks makes text easiest to work with, in several ways:

• It typically results in a text width that's comfortable to work with in a text editor as well as in GitHub diffs and commandline Git diffs.
• Small changes to a paragraph are easy to identify and do not "inflate" diffs:
  • With no line breaks, the entire line shows as changed unless word diff highlighting is used. GitHub diffs do usually highlight word differences, but only up to some limited line length - very long lines do not seem to get word diffs.
  • With hard-wrapped text, the whole rest of the paragraph shows as changed if the word wrapping changes. This works okay with word diff in commandline Git, but not very well in GitHub diffs.
  • With semantic line breaks, neighboring lines usually do not need to change since they are separated at semantically meaningful borders.

Proposed Change

Adopt semantic line breaks as an editorial convention for future changes:

• Do not change existing text to use semantic line breaks.
• When changing text that is not formatted with semantic line breaks, reformat changing lines to use semantic line breaks. Do not reformat unchanged neighboring lines to use semantic line breaks unless it's very few lines, or it otherwise helps readability, or it otherwise seems like a good idea.
• When adding new text, use semantic line breaks.
• Take the Semantic Line Breaks specification as a set of guidelines, not a rigid set of rules. If a contributor proposes changes that clearly do not use semantic line breaks, inform or remind them of the convention and ask them to reformat, but respect their choice of where to place line breaks and do not "bikeshed" the details. The point is to make the text easier to work with, not to enforce a style.
  • In particular, I think the recommended max line length of 80 characters is too restrictive with how much indentation and markup syntax we use. Something more like ~100 characters, or ~80 characters excluding indentation, may be more appropriate for this document. But I don't think we should set a hard limit - use good judgement of where to draw the line in each case.
• Add a notice of this convention to CONTRIBUTING.md.

This should apply to changes made after the decision and to pull requests opened after the decision. Existing pull requests MAY be updated to the new convention, but are not required to apply this convention retroactively.

[timcappalli]

+1. This has been driving me crazy.

[nicksteele]

Should just need an update to README.md for this, thanks for pushing Emil!

[MasterKale]

Looks good to me, thank you Emil for the thorough collection of examples!