Implementing shared CSS <related-links> formatting across the Oxygen editor, PDF Chemistry, and HTML5/WebHelp

[chrispitude]

I am working on a shared CSS file to use in

• The Oxygen editor
• pdf-css-html5 transformations
• webhelp-responsive transformations

I noticed some differences inside <related-links> elements that make the shared CSS a bit challenging:

• <desc> text replaces the link text in the Oxygen editor, but is never shown in the transformation output.
• <link> is a block element in the Oxygen editor, but <a class="topic/link"> is a span element in the transformations.
• In the transformation output, there are <ul class="linklist"> and <li class="linklist"> element, which are different from a <div class="topic/linklist"> element that results from a <linklist> element in the DITA source.
• <a> link elements have @class="topic/link" in the PDF Chemistry HTML, but not in the WebHelp HTML.

Most of these characteristics are inherited from the underlying DITA-OT html5 transformation, so these differences are things to be aware of, and not things to be changed.

However, it would be useful to resolve the last item, so that link elements would have "topic/link" class selectors in WebHelp's HTML (which would match PDF Chemistry's HTML). To Syncro Soft, is this an enhancement request that could be considered?

Here is a testcase for experimentation:

related-links-css-classes.zip

(25.33 KiB) Downloaded 35 times

To see the transformation outputs, publish all deliverables in the "project.xml" file.

The testcase applies CSS highlighting in the Oxygen editor, and in the html5, pdf-css-html5, and webhelp-responsive outputs:

Code: Select all

.topic\/related-links { background-color: yellow; margin: 5pt; padding: 5pt; }
.topic\/link { background-color: pink; margin: 5pt; padding: 5pt; }

.topic\/desc { background-color: lightgreen; margin: 5pt; padding: 5pt; }
.topic\/linktext { background-color: lightblue; margin: 5pt; padding: 5pt; }

.topic\/linklist { border: 4px solid red; margin: 5pt; padding: 5pt; }
.topic\/linkpool { border: 4px solid blue; margin: 5pt; padding: 5pt; }
ul.linklist:not(.topic\/ul) { border: 4px dotted red; margin: 5pt; padding: 5pt; }
li.linklist:not(.topic\/li) { border: 4px dotted blue; margin: 5pt; padding: 5pt; }

which helps to visualize how the CSS selectors are similar/different:

image.png (164.45 KiB) Viewed 473 times

[julien_lacour]

Hi Chris,

An enhancement should be possible, I added an issue to track this improvement and I will post it the status of this ticket.

Regards,
Julien

[chrispitude]

Hi everyone,

With Julien's help, I was able to find an elegant solution to shared <related-links> CSS formatting between the Oxygen editor, PDF Chemistry, and WebHelp!

I want to style the link list as follows, with the links indented by 0.375in, then a Unicode marker character shifted left from that by 0.225in:

see_also_formatting.png (9.01 KiB) Viewed 408 times

In addition, I want any <desc> text to become additional descriptive text, appended to the end of the link:

image.png (12.62 KiB) Viewed 408 times

Julien suggested that I apply a CSS "display: block" property to both the <link> items and :before pseudoelements, instead of using list :marker pseudoelements (which are resistant to styling). Using block elements provides much greater control over both positioning and styling:

Code: Select all

/* link block */
.topic\/topic:root .topic\/link,
html:root .topic\/related-links li.linklist {
    display: block;
    margin-left: 0.375in;
    position: relative;
}

/* link marker block, to the left of the link */
.topic\/topic:root .topic\/link:before,
html:root .topic\/related-links li.linklist:before {
    display: block;
    width: 0.225in;
    position: absolute;
    left: -0.225in;
    content: '\21aa';  /* Unicode down-right arrow character */
}

The ".topic\/topic:root" selectors apply to Oxygen editor elements, and the "html:root" selectors apply to HTML5, PDF Chemistry, and WebHelp elements.

Here is a testcase if you would like to experiment with this shared <related-links> CSS styling:

related-links-common-styling.zip

(26.12 KiB) Downloaded 33 times

To generate the outputs, publish all deliverables in the "project.xml" file.

[julien_lacour]

Hello,

This has been improved since Oxygen 25.0, the generated @class attribute will keep the inherited DITA class.

Regards,
Julien