Additional reformat option for spaces between headings

Enhancement proposal

I love Code > Reformat Code to clean up my asciidoc pages. However, after reformatting there is only a single line before all paragraphs and headings.

For myself, I prefer a little bit more “air” before my headings, two or three lines, say.

Perhaps this could be made into a setting that can be tweaked.

Maintainer notes (by @ahus1)

Good First Issue

This issue is labeled “good first issue”, and maintainers are willing to help. Please comment in this ticket to exchange ideas how this could be implemented. Feel free to pair up with a maintainer to help when you don’t know where to start if when you’re stuck.

Find out more about how to contribute at “Contribute as a coder” in the Contributor’s guide.

Implementation Idea

There has been a pull request #633 that implemented the number of blank lines after a heading. Now as this is about adding blank lines before a heading, implementors can use the code changes performed there as a blueprint to implement this feature request. Please note that the file AsciiDocBlock.java has been renamed to AsciiDocFormattingBlock.java in the meantime.

1. Starting point to add a settings for this would be AsciiDocLanguageCodeStyleSettingsProvider. Then the user can configure this via the settings in “Code Style > AsciiDoc” or via an .editorconfig file.

2. Once the configuration option is available, the formatting in AsciiDocFormattingBlock can pick it up like it already picks up the configuration for ONE_SENTENCE_PER_LINE.

3. There are some existing tests regarding formatting in AsciiDocFormattingModelBuilderTest. The test files are located in folder testData/actions/reformatFileInEditor.

[mminot-yseop]

I agree with this. Generally speaking, I always disable formatting in this extension (and recommend to my colleagues to do the same, to avoid mayhem and needlessly long diffs in pull requests), as I think the default behavior tends to lead to cluttered-looking AsciiDoc files.

Regarding headings, the rule we try to apply in my company is:

= Title

Preamble.


== Foo

=== Bar

Plop


=== Plup

Palala

In other words: two blank lines instead of one whenever a heading is preceded by anything else than a heading. This way the source code makes the structure a lot clearer IMO. The extension squeezes all that into some kind of zebra-crossing-looking list where my brain struggles to find out what is below what.

Similarly, I’m always surprised to see that [source, bash] gets turned to a space-less [source,bash]. It’s really confusing when you’re used to working with programing languages where having a space after commas when allowed is basically the norm. 🤔

[mminot-yseop]

I feel like you’re being rather accusatory rather than trying to politely communicate the behavior you think the formatter should have. Okay, so the formatter may not be catching all the spaces. It’s not perfect. If it was, there wouldn’t be an issue tracker. You can say “I notice that the formatter is not removing all insignificant spaces in the attribute list. Would it be possible to implement it that way?” Saying “this is off-putting” is disrespectful and that tone has no place in this community.

You’re right; while I enjoy these topics, I tend to get emotional about them. 😞 I think the point I was (clumsily) trying to make was: having a formatter is awesome, but it’s a bit inconvenient to have to turn it entirely off when one of the things it does does not suit your needs. I feel like I’m only using a tiny part of the extension as a result. 😐 By “off-putting” I mostly meant that the result feels harder to mentally process, to me. Note that I’m not a native English speaker. 🙇🏻‍♀️