Allow AsciiDoc table cell to be accessed from inner document

[mojavelinux]

An AsciiDoc table cell has a single child node, which is an inner AsciiDoc document. This document can be accessed from the cell node through the inner_document property. However, it's not possible to access the reverse relationship. The inner AsciiDoc document can only access the parent document through the parent_document property. This can make writing extensions that traverse the document tree difficult.

Introduce a new property on the inner document named parent_cell to access the AsciiDoc table cell from the inner document it contains.

Here's an example:

doc = Asciidoctor.load <<~'END', safe: :safe
|===
a|
inner document
|===
END

asciidoc_table_cell = (doc.find_by context: :table_cell, style: :asciidoc)[0]
assert_equal asciidoc_table_cell, asciidoc_table_cell.inner_document.parent_cell

[mojavelinux]

The reason we cannot set parent on the inner document is because that would break the contract that the parent on a document should be nil.

[mojavelinux]

To make this more generic, we could consider parent_node. However, there's no reason we couldn't add that as an alias later.

We could also consider outer_cell (or outer_node) as a corollary to inner_document.

[slonopotamus]

asciidoctor-epub3 currently has to do some hacks due to inability to traverse document tree up from cell document. See asciidoctor/asciidoctor-epub3#473

[mojavelinux]

I wonder if that's reason enough to promote this fix to the 2.0.x series. wdyt?

[slonopotamus]

That would be very nice (and the feature itself looks very safe and nonintrusive). The hardest thing is deciding on the name :) I'm fine with any of outer_cell/outer_node. The latter is more future-proof in case there emerge any new contexts with nested documents. To be honest, I never understood why cell contents is a document at all instead of just a block. I assume this is some kind of legacy.

[mojavelinux]

I assume this is some kind of legacy.

Yes, it was necessary to match compatibility with Asciidoctor's predecessor. (Asciidoctor's predecessor actually shelled out to itself to process an AsciiDoc table cell as a standalone document). It's something we can revisit in the language spec, and is still on the bill to address.