Remove hard line breaks

[c24t]

Following #560 (comment) and #192 (comment), replace hard line breaks with soft ones across the whole repo.

The only change visible in the rendered HTML is to remove some text encouraging the use of hard breaks in b4067f9.

Vim macros did the heavy lifting here: I joined paragraphs that ended at 80 characters and re-broke them around the ends of sentences (i.e. /[.?]\s+[A-Z]). It's possible this added some line breaks where human editors wouldn't have -- or otherwise mangled the text in a way that's not visible in the rendered diff -- but I don't see any egregiously wrong edits after a quick review.

[c24t]

cc @jmacd, @arminru

[jmacd]

Thank you!

[arminru]

Thanks for taking care of this, Chris!
It looks like you replaced a few question marks at the end of sentences with a period in metrics/api.md but otherwise the --word-diff is empty and should therefore be fine.

[bogdandrutu]

I am not sure I understand what do we try to achieve. It seems that this PR removes the idea of "soft limit" and uses "no limit".

I personally don't like to have to scroll right 4-5 screens to read/change a sentence. I am not saying that we should have a hard 100 characters rule, but in this case https://github.com/open-telemetry/opentelemetry-specification/pull/564/files#diff-6a3371457528722a734f3c51d9238c13R20 I have to scroll 2 screens (horizontally) to see the text, which is very annoying.

I think having a hard limit of 200 characters is necessary to avoid scrolling in two directions when reading the code (horizontally and vertically), there may be editors/ide that enforces no horizontally scrolling (I think VIM does that) but some allows that (intelliJ) and it is very annoying (also I am not suggesting you to not use VIM or me to not use intelliJ (because of java)), so we need to find a compromise.

[Oberon00]

We had that discussion already in #192 and decided to use soft line breaks. It just seems that nobody has executed that decision yet 😃

[MrAlias]

💯

[MrAlias]

💯

[andrewhsu]

LGTM ❡

[yurishkuro]

I am soft -1 on this change, because it seems to take the worst of two worlds: the long sentences are still long, so it does not solve the wrapping problem. My preference is to only have line breaks between paragraphs - that's the natural writing style.

[c24t]

(also I am not suggesting you to not use VIM or me to not use intelliJ (because of java)), so we need to find a compromise.

Setting View > Active Editor > Soft-Wrap in intelliJ CE looks to me like it does the same thing as :wrap in vim, or am I missing something here?

[c24t]

My preference is to only have line breaks between paragraphs - that's the natural writing style.

I broke at sentences in this PR because I thought it was a good default, not because I think it's better than paragraph breaks in every case. The goal was just to remove mid-sentence line breaks, not to enforce line breaks after each sentence.

One reason it's a good default is that it produces the shortest sensible line diffs -- changes to a word in a sentence are likely to affect the whole sentence, but not the whole paragraph.

[bogdandrutu]

@c24t can you clarify with @yurishkuro about this approach vs what he is proposing?

[c24t]

@c24t can you clarify with @yurishkuro about this approach vs what he is proposing?

In this PR, instead of adding a line break at the end of each sentence I could have added a line break at the end of each paragraph. One upside of this approach is that the raw text would look similar to the rendered html when viewed in an editor with soft text wrapping, with no line breaks in between sentences. One downside is that it would produce longer line diffs for changes that only affect a single sentence.

Whether to break after sentences or paragraphs is largely a matter of taste, and in general I think it's a good idea to add breaks where semantically appropriate instead of at the end of every sentence as a rule. But since this PR applies the same mechanical change across the whole repo, I think breaking at the end of sentences is a better default.

[c24t]

It looks like make markdown-link-check is getting rate limited by github?

ERROR: 2 dead links found!
[✖] https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto → Status: 429
[✖] https://github.com/grpc/grpc/blob/master/doc/statuscodes.md → Status: 429

This is locally, not sure if we're having the same problem in CI. But I'd be surprised if this PR introduced link errors since it's not changing text.

[yurishkuro]

Whether to break after sentences or paragraphs is largely a matter of taste

I'd say it's a matter of English language. When a paragraph has 10 sentences, each with the length of 130% of screen width, the resulting rendering with breaks after sentence is exceedingly ugly and difficult to read:

..........................
..........
..........................
.....
..........................
........

GitHub has the ability to highlight just the part of the long line that's changed (using different shade of green).

[jmacd]

This PR has been delayed sufficiently long that it will now be causing conflicts, as we are at work on the 0.4 specification. I suggest we close this without merging and try again.

[jmacd]

It's too late for this.

[Oberon00]

@reyang I don't think "release:required-for-ga" can be justified here, changing line breaks in the spec would be a fully backwards compatible change.

[bogdandrutu]

This is outdated, closing for the moment unless we want to rebase this.