Implement smart block (bottom) margins #1515
Comments
|
Since this change will likely break existing themes that customize block margins, it will need to be scheduled for 2.0.0. |
|
It may be possible to support smart margins on either side, which would mean we can avoid breaking compatibility. Regardless, it will still affect some themes since there would no longer be extra space below blocks nested inside of other blocks. |
|
After thinking a lot about how this would work, we've decided to focus on using the bottom margin of a block to strategically control the space between blocks. Before applying the bottom margin, the converter will determine whether the block has a next block within the same enclosure (i.e., next enclosed block). Only if it does will the bottom margin be applied to offset the block from the next adjacent block. The boundary of an enclosure, as defined in this context, is where we would want the bottom margin of the last block to be shaved off so we don't end up with a compounding margin. For example, a sidebar is an enclosure. A top-level list is also an enclosure. The enclosure itself will have its own bottom margin. That's why a top-level list is considered an enclosure, but not a nested list. A section is not considered an enclosure in this context. That's because the next section can be a sibling, parent, or ancestor of the current block. Instead, the margin handling will consider when a block is followed by a section, then add a consistent margin (currently the block_margin_bottom value) to the bottom of that block so the spacing above a section is stable. A cornerstone of the implementation for this issue is the logic to compute the next enclosed block. That logic will need to be properly unit tested to ensure that we are covering all likely permutations. |
|
Here's some more background on how we arrived at this approach: First, we reviewed the existing logic to confirm what margins were being added or collapsed. As expected, the logic is very inconsistent and, in many cases, uses guesswork patches to achieve the right spacing. Ordered and unordered lists, especially when getting into nested lists, is particularly complicated. For example, a list item with primary content only (not multi-paragraph or block content) uses different spacing than a list item with paragraphs or blocks. This spacing complexity expands when one considers the content combinations of (great-great, great-, grand)parent, sibling, and child list items, and whether a list item is the last item in a list. As a person viewing a list, it's easy to identify the last list item in a list (i.e., the list terminus) visually. However, programmatically, the converter has to work through the AST until it identifies the greatest parent of an item and then that there are no other parents, siblings, or children list items following what may be the last list item. Description lists also have unique spacing requirements that include nested items and the possibility of terms without descriptions. Then, we worked through what operations the converter would do to determine:
For example, when a list item has complex content and is the last item in a list and the next object is a section heading is:
We then did the same exercise using top margins only. Both exercises included discussing what the possible results and problems would be if, in the future, we added keys for controlling some of the margins. After working through a number of scenarios, we came up with the following plan:
|
|
Here's a list of the bottom margins that need to be adjusted and reviewed:
We need to look closely at nested list permutations as well. We might not get them all the first time, but the existing tests should still pass with any necessary modifications. |
mojavelinux
changed the title
…vent extra space below blocks, particularly nested blocks
…vent extra space below blocks, particularly nested blocks
…vent extra space below blocks, particularly nested blocks
…vent extra space below blocks, particularly nested blocks additionally, resolves asciidoctor#1513 resolves asciidoctor#1845
…vent extra space below blocks, particularly nested blocks additionally, resolves asciidoctor#1513 resolves asciidoctor#1845
…vent extra space below blocks, particularly nested blocks additionally, resolves asciidoctor#1513 resolves asciidoctor#1845
Block margins should only be applied between block elements. The simplest way to do this is to use top margins and only apply them if the block is not the first child. (We can come back later and implement bottom margins as an alternative).
The only tricky part are list items. List items should have a built-in line-height, so the spacing is still applied below the last item. Additionally, more space should be applied between the end of a complex block and the start of the next list item. We can try to match what we have now, though more control may be needed in the future.
One of the benefits of this change is that a block inside of another blocks (such as a block inside of an AsciiDoc table cell) will no longer have a gap below it.
The text was updated successfully, but these errors were encountered: