merged2html5 -- Modifying xref elems

cud
Posts: 15

merged2html5 -- Modifying xref elems

Fri Sep 07, 2018 3:48 pm

Ok, here's an edge case. To build our release notes we also conref to a list of new features in the product doc. That list of features has xrefs that link to pages in the HTML. The Rel Notes are PDF so those links can't work.

To fix this I make the xref like so:

Code: Select all

<xref outputclass="PDF_External" deliveryTarget="User Guide"href="foo.xml#myId">Configuring a Group for SSO Authentication</xref>


Then I use the following template in the XSLT

Code: Select all

    <xsl:template match="xref[@outputclass = 'PDF_External']">
        <xsl:text>&quot;</xsl:text><xsl:value-of select="."/>
        <xsl:text>&quot; in the </xsl:text>
        <xsl:element name="i">
            <xsl:value-of select="@deliveryTarget"/>
        </xsl:element>
    </xsl:template>


It works like a charm, except for one thing. The

Code: Select all

<xsl:value-of select="."/>
statement gets the content within the xref tags (good), AND it gets the short description of the target topic (bad). Further, it seems to just come across concatenated to the tag content, so I don't see a way to parse it out.

Another odd thing is that some of the attributes come across empty or changed. The href attribute changes, and otherprops comes across empty, for example.

Anyway, is there some way I can get rid of the short description that comes with my tag content? How do you know where to break it off?
Dan
Posts: 298

Re: merged2html5 -- Modifying xref elems

Mon Sep 10, 2018 2:54 pm

Probably you need something like:

Code: Select all

<xsl:value-of select="node() except *[contains(@class, 'topic/shortdesc')]"/>

I have not tested it yet. Take a look at the merged file and modify the selector accordingly.

Many regards,
Dan
cud
Posts: 15

Re: merged2html5 -- Modifying xref elems

Tue Sep 11, 2018 12:59 am

Well, no joy. I played around a little, and actually tried going into the merged2merged entry point to have a look.

For that entry point, I added in this:

Code: Select all

    <xsl:template match="xref[@outputclass = 'PDF_External']">
        <xsl:copy>
            <xsl:value-of select="node()"/>
        </xsl:copy>
    </xsl:template>


The result I get is this (it shows up in the PDF with a yellow background for some reason):

Code: Select all

 [/map/topic/topic/body/ul/li/p/xref {""}) usertext Configuring a Group for SSO Authentication genshortdesc To use SSO authentication in Turbonomic, you should configure user groups on the IdP. The IdP can authenticate the group members, and then Turbonomic can assign the user role and scope according to that group's authentication. (xref


What's interesting here are the two items... "usertext" and then "genshortdesc"

I'm guessing that you (or the OT in general???) look at xrefs in a pre-pass and do some things. One thing is to build out the usertext and the shortdesc into something special (something that displays the usertext as a link, and the shortdesc as a tooltip if you hover over the link? Totally guessing here, but it seems that's one popular use for shortdesc.) Another thing you seem to do is determine whether the link is valid or not... Is there a target.

If I comment out that experiment, and use the merged2html5 entry point to print out the attributes in the xref, I get the following:
attribute name: class attribute value: - topic/xref
attribute name: deliveryTarget attribute value: User Guide
attribute name: href attribute value: #unique_3
attribute name: broken-link attribute value: true
attribute name: outputclass attribute value: PDF_External
attribute name: type attribute value: topic

The two italic attributes are ones that I added... The others are yours. You can see that you identified this as a broken link (correctly), and moved the href out of the xref element into some other location. But the xref does not have anything in it that can help me to throw away the shortdesc text, as far as I can see.
Dan
Posts: 298

Re: merged2html5 -- Modifying xref elems

Tue Sep 11, 2018 2:16 pm

I do not understand exactly what happens, can you post here the fragments corresponding to the xref link as it appears in the .merged.xml and merged.html files from the output folder? Are you modifying the merged2merged or merged2html5 XSL processing?

Let's take a look at how the plugin works:
1. A big file with the expanded topics preserving the map structure is created by DITA-OT.
2. This file is processed using the merged2merged.xsl file resulting in a merged.xml file in the output folder.
3. Next, this file is processed by using the merged2html5.xsl file resulting a merged.html file in the output folder.
4. The CSS processor converts this HTML file to PDF.

You can add extensions to the XSL processing involved in points 2 (merged2merged) and 3(merged2html5).

Assuming your the template is used only in point 2, It needs to copy also all the attributes. Why? Because the Step 3 XSL templates are based on matches on the class attributes (and others).

Code: Select all

<xsl:template match="xref[@outputclass = 'PDF_External']">
        <xsl:copy>
            <xsl:copy-of select="@*">

            <xsl:value-of select="node()"/>
        </xsl:copy>
</xsl:template>


However, the <xsl:value-of select="node()"/> will give you all the text content of all child nodes of your xref, so we need to take a look better at its structure. So, please post the fragments from the merged files.

Many regrads,
Dan
cud
Posts: 15

Re: merged2html5 -- Modifying xref elems

Tue Sep 11, 2018 4:35 pm

Dan... Thanks again! You keep coming through with solutions. Understanding the process helps a LOT. You didn't just give me a carp, you taught me how to fish.

Here's the xref in the merged XML file:

Code: Select all

          <xref class="- topic/xref "
            deliveryTarget="User Guide"
            href="#unique_3"
            broken-link="true"
            outputclass="PDF_External"
            type="topic">Configuring a Group for SSO Authentication
            <desc class="- topic/desc ">To use SSO authentication in
              <ph class="- topic/ph ">Turbonomic</ph>, you should
              configure user groups on the IdP. The IdP can authenticate the group members,
              and then <ph class="- topic/ph ">Turbonomic</ph> can assign the user role
              and scope according to that group's authentication.
            </desc>
          </xref>.


Indeed, it includes the desc element. All I need to do is get the content of the xref element, without the content of its children. So I use the following to do that in my merged2html5 xslt transform (somehow normalize-space drops the children):

Code: Select all

    <xsl:template match="xref[@outputclass = 'PDF_External']">
        <xsl:text>&quot;</xsl:text>
        <xsl:value-of select="normalize-space(text())"/>
        <xsl:text>&quot; in the </xsl:text>
        <xsl:element name="i">
            <xsl:value-of select="@deliveryTarget"/>
        </xsl:element>
    </xsl:template>


And it works... Here's the resulting sentence in the merged HTML

Code: Select all

see "Configuring a Group for SSO Authentication" in the <i>User Guide</i>.


I could actually just match the broken-link attribute, then IF it has a deliveryTarget value, branch into building that text version of the XREF, and IF NOT, post a BROKEN LINK warning in the PDF. That would help proof-reading the PDF before sending it out.

LESSON LEARNED:
To inspect what the merge to HTML operates on, just look at the merged XML. From there, you know how to implement the merged2html5 transform.
Dan
Posts: 298

Re: merged2html5 -- Modifying xref elems

Wed Sep 12, 2018 11:50 am

Maybe a CSS rule to hide the desc element could work as well.
I am glad you worked it out!

Best regards,
Dan

Return to “Common Problems”

Who is online

Users browsing this forum: No registered users and 0 guests