Improvements to section refs

[Andrew-Morozko]

Currently section refs are pretty useless: they can only override the meta block or the title of the base section. However, it's possible to track the position of blocks relative to the base attribute, allowing users to prepend/append content to the base:

section "B" {
    content text {
        text = "B"
    }
}

section ref "ABC" {
    content text {
        text = "A"
    }
    base = section.B
    content text {
        text = "C"
    }
}

document "test" {
    section ref {
        base = section.ABC
    }
}

Produces A\nB\nC\n

[traut]

I like the idea!

I would object to the base attribute position tracking though -- it will be confusing if the order of the attributes (base) is meaningful here but not anywhere else. We should avoid introducing special cases as much as possible, so I wonder if we can come up with a different, clearer, syntax.

Maybe section-specific blocks named prepend and append? They can be just syntactic sugars around embedded section blocks.

For example:

section "B" {
    content text {
        text = "B"
    }
}

section ref "ABC" {
    base = section.B

    prepend {
        content text {
            text = "A"
        }
    }
    append {
        content text {
            text = "C"
        }
    }
}

document "test" {
    section ref {
        base = section.ABC
    }
}

With this logic:

• if prepend block is specified inside section block, it is treated as an embedded section block that is prepended to the sections / content blocks in the base block
• if append block is specified inside section block, it is treated as an embedded section block that is appended to the sections / content blocks in the base block
• if any sections / content blocks are defined in the ref block, they override the section / content all blocks in the base block

What do you think, @Andrew-Morozko?