Implementing shared CSS table formatting across the Oxygen editor, PDF Chemistry, and HTML5/WebHelp

[chrispitude]

I am implementing CSS files to be shared across

• the Oxygen editor
• PDF Chemistry output
• HTML5/WebHelp output

Table formatting proved to be tricky, because CSS table formatting works very differently in the Oxygen editor versus HTML-based outputs.

In addition, I needed to implement default borders like this (color/thickness used for emphasis):

image.png

but these default borders should be overridden by any <table frame="..."> or @rowsep/@colsep settings.

Here is what I found:

• In the Oxygen editor, <table frame="..."> styling is applied to <tgroup> elements.
• In PDF Chemistry and HTML5/WebHelp, <table frame="..."> is styled on <table> elements.
• In the Oxygen editor, @rowsep is set on <row> elements.
• In PDF Chemistry and HTML5/WebHelp, @rowsep becomes "rowsep-0" and "rowsep-1" @class values on <row> elements.
• In the Oxygen editor, @colsep is set via @colsep attributes in <colspec> elements.
• In PDF Chemistry and HTML5/WebHelp, @colsep becomes "colsep-0" and "colsep-1" @class values on <entry> elements.
• In the Oxygen editor, row separators must be applied to <entry> elements because they are ignored on <row> elements.

I could not figure out how to style @rowsep/@colsep in the Oxygen editor.

Here is a testcase showing how to apply common CSS table styling:

oxygen_table_frame_experiments.zip

The borders are color-coded as follows:

• Red borders represent <table frame="..."> borders.
• Green borders represent @rowsep/@colsep borders.
• Blue borders represent the default border styling.

To build the PDF Chemistry and HTML5 deliverables, build all deliverables in the "project.xml" file.

[chrispitude]

I ran into an interesting difference in how table margins behave between the Oxygen editor, PDF Chemistry, and WebHelp (i.e. browser behavior).

Normally, the bottom margin of one element "collapses" with the top margin of the next element, using the largest value instead of adding them together:

image.png

In the Oxygen editor and in PDF Chemistry, <table> margins collapse normally. However, WebHelp applies an "overflow-x: auto" CSS property to tables that causes their margins to no longer collapse. (The technical reason is that any "overflow-x" value besides "visible" causes a new block context to be created in the page layout.) As a result, the margins become additive with adjacent elements when the WebHelp output is viewed in a browser:

image.png

The "overflow-x: auto" property is useful on tables because it allows the browser to dynamically add scroll bars as needed. However, the disabling of margin collapse can result in larger-than-expected blank space around tables, as compared to the Oxygen editor and PDF Chemistry.

To work around this, you can use some CSS like this:

Code: Select all

@media screen {
    /* "overflow-x" values other than "visible" create a new block context
     * that disables margin collapse with adjacent elements */
    .simpletable-container, .table-container, .tablenoborder {
        overflow-x: auto;  /* explicitly reapply property from topic.css */
    }

    /* zero out table margins on these non-margin-collapsing elements,
     * and rely on the preceding/following elements to provide their own margins */
    html:root .topic\/table,
    html:root .topic\/simpletable {
        margin-top: 0;
        margin-bottom: 0;
    }

    /*  re-add margin between consecutive zero-margined table elements */
    :is(.simpletable-container, .table-container, .tablenoborder)
      + :is(.simpletable-container, .table-container, .tablenoborder) {
        margin-top: 40px;
    }
}

which (1) applies zero margin around tables, then (2) re-adds margin between consecutive table containers. This solution relies on the elements before and after a table to provide their own reasonable margin values.

Here is a testcase where you can experiment with this workaround:

webhelp_table_margin_collapse.zip

Just publish the deliverables in the "project.xml" file.