Consider not using hard line-breaks in specification text

[glen-84]

• It creates unnecessary diffs where it's difficult to see what changed.
• It means that most GitHub-applied suggestions require the document to be reformatted afterwards.
• It makes it more difficult to search the source text – I just tried to search for but is not used by the, but it wasn't found because there was a hard line-break before the.
• It's just not natural for prose, and doesn't allow viewers to control the display width.
• etc.

An example (small) diff can be seen here.

I decided to create an issue first, to gather some interest before it's (potentially) brought to a meeting.

[glen-84]

@benjie Could you discuss this in a WG meeting?

[martinbonnin]

Semantic line breaks are a thing: https://sembr.org/

@benjie proposed a patch on prettier: prettier/prettier#17544

That would be nice to have, preferrably immediatly after the next spec cut.

A fork is not ideal. But we could patch prettier inline.

[martinbonnin]

@glen-84 would you be open to look into the above. It seems like a compelling solution.

[glen-84]

Both GitHub and VS Code highlight changes within a modified line/paragraph, so I'm not really convinced that semantic line breaks are necessary.

It seems a bit unnatural to me, unlike how you would edit prose in a word processor, for example.

A spec editor would either have to insert the line breaks themselves, or the text would jump around a lot when saving with automatic formatting.

[martinbonnin]

Sorry, my previous comment was written live during the last issue club and I failed to add more context at the time.

@benjie can you ellaborate a bit more why semantic libe breaks would be useful here?

[benjie]

With paragraphs all on one line diffing was painful, it’s also not ideal for editing, can be unwieldy, and also problematic when rendering raw markdown in certain places/tools, requiring horizontal scrolling. This is why we moved to prose wrap… but that caused issues in the other direction. Semantic line breaks strikes the middle ground: lines don’t get too long, but entire paragraphs don’t re-wrap when you edit a single word.

[glen-84]

With paragraphs all on one line diffing was painful

What kind of diffing? Can you show an example?

it’s also not ideal for editing, can be unwieldy

But this is how everyone writes prose in word processors? How is it unwieldy?

and also problematic when rendering raw markdown in certain places/tools

Tool issue. 🙃