"Keep line breaks" option

[Vampire]

Some other languages like Java and Kotlin have an option in the formatter to "Keep Line Breaks" while reformatting.

This does not mean that for example if you have 3 blank lines, they are preserved, those get reduced.

But this option is effective on some other places.

It would be great to have also such an option for Asciidoc.

Where I right now wish it would be considered is for "One sentence per line".

Germans tend to write much longer sentences than Englishmen.
I usually prefer to split the sentence to multiple lines around 80-100 characters.
So for example formatting with "One sentence per line" this:

First sentence. Second sentence. Third sentence.

would always produce

First sentence.
Second sentence.
Third sentence.

like now.

But formatting

A long sentence that is
intentionally broken to multiple
lines for better readability even
without a soft-wrapping editor.

would stay like that with the new option enabled, while currently and without the option it would be changed to

A long sentence that is intentionally broken to multiple lines for better readability even without a soft-wrapping editor.

[ahus1]

Hi @Vampire - there is an option in the AsciiDoc plugin's settings in Code Style where you can disable the "One sentence per line" rule. This might solve the examples given above. See the screenshot below where to change this.

Still there are several reasons why to use the one-sentence-per line, see https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line
When using it, I recommend to enable word-wrap for AsciiDoc files for long lines. See #1551 for a similar discussion.

Please let me know if this resolves your situation.

[Vampire]

Thanks, but I am fully aware of that option and I even mentioned the option in my description twice.

There are two aspects to the "One sentence per line".
One aspect is that it splits lines with multiple sentences into multiple lines.
The other aspect is that is joins sentences that are split over multiple lines into one line.

Also the reasoning for the "One sentence per line" best practice has similar two aspects.
One aspect is the advantages not to have multiple sentences on one line.
The other aspect is the advantages not to have one sentence split onto multiple lines.

The only reasonings on that best practice paragraph that imho describe advantages of not having a sentence split onto multiple lines are:

It prevents reflows (meaning a change early in the paragraph won’t cause the remaining lines in the paragraph to reposition).

I personally don't really care about that.
A proper diff tool can properly display that, or you don't need to rebreakt as it is not about "breaking at a fixed width" like the paragraph started with, but just doing it sanely manually.

You can spot sentences which are too long or sentences that vary widely in length.

Well, some sentences are longer some shorter, where is the problem?
I really don't care about this "advantage".

The drawback of having very long sentences on one line though are, that without softwrapping they easily start to be very hard to read. Not every editor supports soft-wrapping. Not every web-application supports soft-wrapping. Not every E-Mail client that might display diffs supports soft-wrappgin. ...

Also the sentence

This technique is similar to how you write and organize source code. The result can be spectacular.

is exactly right, while imho text and code are two majorly different things and should not really be compared.
But now that the comparison is made, I usually do not put multiple statements in one line as that makes the code harder to read, yes.
But I surely regularly, if not daily, split long code lines with one statement into multiple lines to improve readability enormously.

And that same I would prefer to do with text.
Split long lines into multiple to improve readability, also in tools that do not support soft-wrapping,
while maintaining the best practice to have at most one sentence per line.

Of course I can disable that option and do it completely manually, and that is what I do right now.

But I thought it would be beneficial if you could have it enabled, with the option to keep line breaks just like in other formatters, so that the option can split for me lines with multiple sentences but does not touch my sentence on multiple lines.

If you really don't like it, feel free to close this as wont-fix, no problem for me even if a bit sad. :-)

[ahus1]

Thank you for the explanation, I now see understand the behavior you want to see.

I won't discuss the "One sentence per line" here, though, as it is out of scope for this issue.

I mark it as "help wanted" and wait if someone picks it up. If there are no votes and no-one picking it up, I might eventually close it.

[schapsl]

Hi @ahus1,
I agree with @Vampire. I also like to split up long sentences with multiple parts (Hauptsatz, Nebensatz) into multiple lines with one part per line. Imho, this does not only improve the readability of the code, it also avoids having a long sentence in one single line, which is more likely to produce merge conflicts in a VCS.
And these sentences will be cut off, if you use something like "git diff" in a terminal.
Also it's easier to alter sentences and rearrange parts, which I do a lot while I'm writing.

My suggestion would be like the one from @Vampire, to introduce a new parameter "Keep line breaks", which depends on the "One sentence per line".

If appreciated, I could make a PR, where the new parameter would be evaluated in the block following
[AsciiDocFormattingBlock.java#L156]:

asciidoctor-intellij-plugin/src/main/java/org/asciidoc/intellij/formatting/AsciiDocFormattingBlock.java

Line 156 in 9696bf1

// ensure exactly one space between parts of one sentence. Remove any newlines

[ahus1]

@schapsl - sorry for the long wait. Yes, please go ahead with a PR.