Feature Request: Support for nested list margins

[mcp292]

I see I can control item-spacing, but it would be nice to control nested item spacing separately.

Having the nested item remain close to its parent enforces the connection.

[mojavelinux]

There is already some logic to collapse spaces between list levels (though it is rather complicated). Can you give a concrete example that shows which space you are trying to remove?

[mcp292]

If I have this list

. Parent1
.. Child
. Parent2
. Parent3

I'd like to control the spacing through the theme with the following keys

. Parent1
// nested-item-spacing
.. Child
// item-spacing
. Parent2
// item-spacing
. Parent3

[mojavelinux]

Thanks for providing that example. I'm not sure I understand what the problem is. The spacing is already adjusted so that the margin above the nested list is collapsed. Is that not sufficient?

[mcp292]

It seems to be treated as a normal list item with item-spacing applied to it.

[mojavelinux]

Right, that's what I'm saying it does. What I don't understand is what you want to see instead.

I would also need you to propose how the customization you are looking for would be expressed in the configuration.

[mcp292]

I want to specify in the theme

outline-list:
  item-spacing: 7
  nested-item-spacing: 4

and have the spacing applied in these locations

. Parent1
// nested-item-spacing
.. Child
// item-spacing
. Parent2
// item-spacing
. Parent3

which would make the spacing between 1. and a. be less than the spacing between a. and 2. in this image

[mojavelinux]

nested-item-spacing: 4

The problem with this proposal is that it doesn't make sense to talk about a nested item as there's no such thing. There's a nested list, which has its own margins. What Asciidoctor PDF does is suppress the margins around the nested list so that the first item doesn't get offset more than an item in the top-level list. So we could talk about a nested-list-margin perhaps. But the space between items in a nested list would still use item-spacing (as it does currently).

I honestly don't see any different in the spacing in the two screenshots you provided. Given it is so slight, is this really that important?

[mcp292]

Okay I've identified some confusion. The screenshots are identical and just repeated for clarity in the more detailed explanation. In the picture there is no difference between the spacing for the list items or what I was calling the nested list item. I'm just using it to reference where the changes would take effect.

You previously stated

The spacing is already adjusted so that the margin above the nested list is collapsed.

but I'm not seeing any spacing being collapsed. What I would expect if it were collapsed is for the spacing between 1. and a. to be less than the spacing between a. and 2. or 2. and 3., which it's not. All mentioned spacing appears to be equal to each other and to list-item-spacing.

You're now explaining that the nested list is its own entity with its own margins, and I'm interpreting those margins as being collapsed to have spacing match list-item-spacing.

My current understanding:
Since nested list has its own margins, we can change them separate from the list margins, but because the margins I'm interested in get collapsed (margin-top) it won't make a difference in the end product.

I don't see any documentation for nested-list in the theming guide.

[mojavelinux]

I'm not seeing any spacing being collapsed...All mentioned spacing appears to be equal to each other and to list-item-spacing.

Correct. What I mean is that the margin around the nested list is collapsed so that there's no extra space. In other words, the distance between the primary text and the nested list is the same as the distance between two list items. This matches the behavior of the default styles for both HTML and EPUB3, so it is consistent across the ecosystem.

The reason this is the default is because when this was not done, people complained that there was extra space around the nested list. Since we fixed it, I have never heard a complaint until now.

What I would expect if it were collapsed is for the spacing between 1. and a. to be less than the spacing between a. and 2. or 2. and 3.,

I really just don't see why you would want that. It's already offset with indentation. Why does the vertical space need to be condensed? Can you point to somewhere where this style is used for reference?

You're now explaining that the nested list is its own entity with its own margins, and I'm interpreting those margins as being collapsed to have spacing match list-item-spacing.

Yes, that's the current behavior.

Since nested list has its own margins, we can change them separate from the list margins, but because the margins I'm interested in get collapsed (margin-top) it won't make a difference in the end product.

If we made it configurable, then it would be configurable. I was just explaining how it works now.

I don't see any documentation for nested-list in the theming guide.

That's because it's not currently something you can control. It's something you would need to propose.

[mcp292]

Okay we're on the same page now. Do with it what you will.

[mojavelinux]

To be clear, I'm not against being able to control the margin above a nested list. I'm trying to clarify the current situation and help refine the proposal so it's something that fits with how Asciidoctor PDF works. I don't have time to design and implement it, so the proposal has to be strong enough for a contributor to be able to follow. And that means we need to get to the point where the theme keys and how they will be applied is clearly defined.

[mcp292]

Thank you for the added context. That makes a lot of sense and I am happy with where we left off. You make a good point

It's already offset with indentation. Why does the vertical space need to be condensed? Can you point to somewhere where this style is used for reference?

I don't have any example of this in use and so I leave it to your judgement as you have more experience with writing styles and guidelines than I do. So far Asciidoctor supports best practices and industry standards, and if this request goes against that, maybe it's not worth supporting.