Support [.pagewide] role for tables and images

[alexandre-frey]

Text content can now be globally indented (theme property section_indent, see #737).
But then, a table that has the [.stretch] role is only stretched to that section indent, not to the page margin.
It is useful for some wide tables to stretch them to the page margins.
I suggest the converter should support the role [.pagewide] for that. The role should be applicable to tables and to images.

[alexandre-frey]

I implemented this role in a custom converter. Here is the code for tables:

#
# Implement the role ".pagewide" for tables. The effect is to strech 
# the table up to the page margins, instead of only to the section width
#
def convert_table node
    if (node.has_role? 'pagewide')
        indent_l, indent_r = inflate_indent @theme[:section_indent]
    else 
        indent_l, indent_r = 0,0
    end
    indent -indent_l, -indent_r do
        super
    end
end

[mojavelinux]

I like this idea, but I'm not convinced the name is correct. Page-wide implies that it stretches the width of the whole page. In fact, we have a similar option for block images already named align-to-page. What we're really talking about here is column-wide.

If you only anticipate needing to make the table break out of the section indent, then I would suggest the option name outdent. If you anticipate also wanting to stretch the table edge to edge of the page, then we might need an attribute like relative-to=page|column.

[mojavelinux]

Basically, this feature needs terminology improvement. The idea is great.

[mojavelinux]

How do you feel about container-wide as the role name?

[alexandre-frey]

Hi! I initially thought pagestretch, but you suggested pagewide in this comment.
To be honest, I don't have a preference, pagestretch, pagewide, container-wide are fine.
Note that in DITA, the system I'm trying to replace with asciidoc, the attribute is called pgwide and means "1=page width; 0=resize to galley or column".

[mojavelinux]

Note that in DITA, the attribute is called pgwide...

That's very useful input. I'll dig into that.

[mojavelinux]

To follow up on that, here are the docs from DITA:

For PDF, the value "1" places the element on the left page margin; "0" aligns the element with the left margin of the current text line and takes indention into account.

So it's clearly a toggle, which would be best suited by a role (e.g., %pagewide).

[mojavelinux]

DITA also has an attribute named expanse which has a very similar purpose. The values are page, column, and textline. Perhaps we could consider the option name %expand. So to make a table that stretches to the page margins, you'd use .stretch%expand.

Here are the two proposals on the table:

• .stretch%expand
• .stretch%pagewide

At first, I had said page-wide could be confused with the width spanning from edge-to-edge of the document, but I now realize it would be more appropriate / accurate to refer to that as the canvas (i.e., canvas-wide).

If we do anticipate needing both of those options for other elements (like an image), perhaps we should consider an enumerated attribute:

• extent=container (default)
• extent=page
• extent=canvas