PDF-CSS: Creating new CSS counters for new types of figures

[jcb_mgc]

Hello, I need some advice on adding additional CSS counters to the PDF-css scenario for custom types of figures.

In addition to the default figures, we also have examples and equations. We would like the captions and counters on these types to be "Example N", and "Equation N", where N is a counter for the respective type. The counts for each of these 3 types must be distinct. Therefore, the already defined 'figcount' css counter is placed on default figures, and we need to create and add two additional css counters for examples and equations.

We have already implemented custom CSS for counting our custom types, and it works for captioning and numbering the item itself, however, when we have elements that refer to these custom types, it uses the figcount counter and caption. For example, if we have an <xref> that targets an equation, the caption on this <xref> is "Figure XX", and the count XX is incorrect (it is the figcount counter, not our custom counter).

This mismatch in captions and count for xrefs makes me think that our custom CSS for our custom types is implemented incorrectly. Indeed, when I search the com.oxygenxml.pdf.css plugin for "figcount", I see dozens of resets, increments, and usages. Currently we use an outputclass attribute on the figure with our own custom value ("ExampleTitle", "EquationNum") to count these things. For internationalization, we look up the caption in XSLT, like the XHTML build does it.

For <xref> elements, I see that a <span> is inserted, and this span has a class attribute value of "- topic/ph ph fig--title-label-number ". The string "fig--title-label-number" is also used in a <span> element within the fig itself. I have found XSLT where these are inserted, and "fig--title-label-number" seems to be hardcoded, so that the <xref> always uses the figcount counter.

Sadly, I just don't understand the connection between the <span> elements in the <xref>, and the <span> element in the figure. How do these two work together with the CSS to produce the caption and count?

I would appreciate some guidance on best practices for implementing new CSS counters -- it seems that what we have done so far is both incorrect and incomplete (in terms of internationalization of the words "Figure", "Example", and "Equation").

Thanks,
-J

[julien_lacour]

Hello,

You have a really interesting use-case, for this kind of complete scenario, I recommend the usage of a publishing template file (if you didn't use it already). You can find more information in our user-guide.

If you struggle with your CSS customization, you can try to debug your style-sheet to see how the different rules are applied.
This will surely help you for the internationalization of your CSS rules.

The figure numbering is mainly generated from XSL style-sheets, so in order to add your custom counter you must alter those style-sheets. In order to do that you must extend the 'com.oxygenxml.pdf.css.xsl.merged2html5' extension point (you can directly do this in the publishing template file).
The .fig--title-label-number span is generated using XPath to count figures occurrences in the whole document. Then this fragment is copied when you refer it using xref (also using XSLT template).

For more guidance you can send us a small sample (you can randomize the content from Oxygen > Help > Support tools) at support@oxygenxml.com. We just need the ditamap (or bookmap) file, the related DITA topics (only those with equations and examples) and your publishing custom files (CSS, XSL style-sheets and maybe publishing template file).

Regards,
Julien

[jcb_mgc]

Hi Julien, thanks for helping!

We already have a publishing template set up, and I am overriding the template "place-fig-lbl" XSLT. By overriding this template, I can insert a span under the <figcaption>, for example:

Code: Select all

<span class="fig--title-label-number"> 2</span>

I have confirmed that I can change the class attribute based on the type of figure. For example when we have a figure with outputclass "ExampleTitle", I create a <span> as follows:

Code: Select all

<span class="example--title-label-number"> 2</span>

But I think this is only half of the equation. Now I need to be able to use the class "example--title-label-number" in the <xref>, and of course add a counter for it in CSS. This is the part that is tripping me up.

The figure numbering is mainly generated from XSL style-sheets, so in order to add your custom counter you must alter those style-sheets. In order to do that you must extend the 'com.oxygenxml.pdf.css.xsl.merged2html5' extension point (you can directly do this in the publishing template file).
The .fig--title-label-number span is generated using XPath to count figures occurrences in the whole document. Then this fragment is copied when you refer it using xref (also using XSLT template).

I can't see where the fragment is copied into the <xref> that targets my "Example" figure. When I examine the final merged HTML file, I see <span> elements under the emitted <a>, but they still have the "fig--title-label-number" class:

Code: Select all

<span class="- topic/ph ph fig--title-label-number " outputclass="fig--title-label-number ">16</span>

In my example, you can see that the XSLT has placed the correct count of "Example" figures (2), however, the <xref> that targets the example has the figure count (16), not the example count.

Where is the XSLT that copies the fragment from the figure to the xref? And, why don't I see my "example--title-label-number" class attribute value? It sounds like I shouldn't need to override any more XSLT; it sounds like once I have my <span> in place with the correct value, it will be copied to the <xref>.

I think I'm on the right track, I just can't find the connection between the <span> that lives with the figure caption, and the <span> that lives with the <xref>.

Thanks again for your help!
John

[Dan]

Yes, you will have to override also the templates that compute the link text.
You may find them in this stylesheet:

Code: Select all

oxygen-publishing-engine-3.x/plugins/com.oxygenxml.pdf.css/xsl/merged2merged/merged-links.xsl

Look at those having the mode set to "retrieveReferenceTitle". You may have to copy and modify some of them in your publishing template.

Let us know if you need more information.
Many regards,
Dan Caprioara

[kgajda]

Hi Dan - Sorry, I know this is an older post, and for PDF, but I am essentially looking to do something very similar for our webhelp. Or rather, someone at my organization in the past created an extension that did something that accomplished this, but that legacy code is outdated and will not migrate up to the the new OT so I need a new solution.
Would the same advice you gave apply to me if I want to separate figures from equations in our custom responsive webhelp?

I am writing a whole new plugin to migrate to the new OT (3.7.4) and bringing many of our legacy extensions along with it (if they are able to be integrated or be fixed), so just point me to what all I need to do and override. And thank you for your help!!

[julien_lacour]

Hello,

The following CSS rules should replace the text before <equation-figure>:

Code: Select all

.equation-figure .fig--title-label {
  display: none;
}
.equation-figure .fig--title::before {
  content: "Equation: "
}

For the counters part, there's no global context as in PDF so if you create such counters you will have Figure 1, Equation 1, etc. in each topic.

Regards,
Julien