Lines breaks

[lcawl]

The line breaks work differently than I expected. Per https://github.com/elastic/docs-builder-example/blob/main/docs/source/markup/sundries.md#line-breaks "You can break a paraghraph
using \ at the end of a line."

However when I cut and paste content from the elasticsearch repo, where it seems it was assumed that you had to have a defined line length and content wraps despite that, those EOL were appearing as-is in my output. For example:

The latest stable version of {{es}} can be found on the
[Download {{es}}](https://www.elastic.co/downloads/elasticsearch) page. Other
versions can be found on the [Past Releases page](https://www.elastic.co/downloads/past-releases).

If this is working as designed I think we need to be very clear in the style guide info that what you see in your source file is exactly what appears in the output where line breaks are concerned.

[Mpdreamz]

This is currently be design, most markdown system use soft breaks as real breaks.

Also as per guidance on:

https://www.markdownguide.org/basic-syntax/#line-break-best-practices

You can use two or more spaces (commonly referred to as “trailing whitespace”) for line breaks in nearly every Markdown application, but it’s controversial. It’s hard to see trailing whitespace in an editor, and many people accidentally or intentionally put two spaces after every sentence.

Ending it with \ to force a line break also feels clunky to. Let real line breaks be real line breaks in the documentation.

I could make this a docset setting but I think its best we choose one blessed way to do this across all repositories.

@KOTungseth @bmorelli25 thoughts on this?

NOTE: I need to update the style guide to better reflect what our system does versus the sphinx guidelines it was copied from.

[KOTungseth]

The goal is for the output to replicate the source file, and I agree that forcing a line break with a \ feels clunky. This works as designed.

I also agree we'll need to clearly define this behavior in the style guide (cc: @jmikell821).

[bmorelli25]

I disagree. Forcing entire paragraphs onto one line makes writing, scanning, and reviewing harder in my opinion. I prefer breaking thoughts into separate lines for readability and to be able to make code review suggestions for individual sentences. That being said, our markdown should be predictable. And if predictable is treating soft returns as real returns (I think it is) then I think that's what we should do.

My bigger concern is the potential impact of this syntax decision on our migration work. Writers and engineers are used to writing in our current system where they can assume adjacent lines of text will combine into one paragraph at build time. We likely have thousands of lines of existing documentation that would need to be reformatted to support this new syntax rule.

@siamakp-elastic, does your migration approach address this? Since your tool uses Asciidoctor processors to convert to Markdown, I assume all lines in a paragraph are treated as a single node and processed and output as a paragraph on a single line. Can you confirm?