Page 1 of 1

Where are these related topic links coming from?

Posted: Wed May 22, 2019 3:10 am
by Carl
I have this perplexing problem that I've been wracking my brain over, but I can't figure it out.

I have started adding related topics links to the end of my topics. I do this by selecting Link icon > Related link to topic. In authoring mode, it shows up as "Related information:" and the underlying XML tag is <related-links>.

Here is where the weirdness starts. Our documentation comprises of two guides: UI and System. It was set up so each have their own ditamap. This makes it easy to PDF each guide. However for the WebHelp output, we wanted both to be merged into a single doc set, so there is also a "Main" ditamap which includes both the UI and System ditamaps as children.

Now, when I do a WebHelp transform on the "Main" ditamap, the resulting output shows a "Related information" section that does NOT exist in the topic (for certain topics only)! This phantom section does contain relevant information though and it could be something I might have added at one point and then removed. But as of this moment, these topics do not have a related topics section added to them, yet it appears in the output.

Further debugging: when I generate a WebHelp from the actual "UI" ditamap (i.e., not using the parent "Main" ditamap), the resulting output does NOT show these "phantom" related links! It accurately reflects whats in the topic.

Clues that may help: when I add related topics for real, they come out as "Related concepts" in the WebHelp. But when I see the "phantom" section, it shows as "Related information".

Delving into the source code of the WebHelp page, I see this for the "phantom" section:

Code: Select all

<div class=" wh_related_links "><nav role="navigation" class="related-links"><div class="linklist"><strong>Related information</strong><br /><div class="related_link"><a class="navheader_parent_path" href="../derived_data/derived_system_metadata.html" title="Derived - System Metadata Tab">Derived - System Metadata Tab</a></div><div class="related_link"><a class="navheader_parent_path" href="../derived_data/derived_metrics_metadata.html" title="Derived - Metrics Metadata Tab">Derived - Metrics Metadata Tab</a></div><div class="related_link"><a class="navheader_parent_path" href="../derived_data/derived_parent_metadata.html" title="Derived - Parent Metadata Tab">Derived - Parent Metadata Tab</a></div></div></nav></div>
Note that is begins with <div class=" wh_related_links ">. Does "wh_related_links" mean anything? What about the blank space between "wh_related_links" and the opening and closing quotes? I find that kind of odd.

I hope you can shed some light on this perplexing issue.

Re: Where are these related topic links coming from?

Posted: Thu May 23, 2019 12:05 pm
by Radu
Hi,

If you open the main DITA Map in the Oxygen DITA Maps Manager view and there you right click one of those topics which appear in the related links section you can use the "Search References" action to search all references to it. Maybe for example you have a relationship table defined in one of the DITA Maps...

Regards,
Radu

Re: Where are these related topic links coming from?

Posted: Thu May 23, 2019 7:44 pm
by Carl
Yes, you are right Radu--relationship tables are in effect! I didn't know about these. Thanks!

Re: Where are these related topic links coming from?

Posted: Thu May 23, 2019 8:16 pm
by Carl
On a related note, I see that the relationship tables that were set up uses "Related information" as the header, and that's what shows up in our topics: "Related information". But when I manually add related topics, they usually come up as "Related concepts" (because most of my topics are Concepts). If it's linked to a Task, it shows up as "Related tasks".

How do I make them all appear simply as "Related topics" in my WebHelp, regardless of whether I'm linking to a Concept or a Task? I've decided I don't want to use relationship tables.

Re: Where are these related topic links coming from?

Posted: Fri May 24, 2019 9:04 am
by Radu
Hi,

You can take control in the DITA content over the title presented for the manually added links:

Code: Select all

    <related-links>
        <linklist>
            <desc>Related topics</desc>
            <link href="../concepts/springFlowers.dita"/>
        </linklist>
    </related-links>
Otherwise maybe you can try a CSS customization, see in what part of the output HTML document that static text is generated and maybe hide it using CSS and add some static text in place.

Regards,
Radu

Re: Where are these related topic links coming from?

Posted: Fri May 24, 2019 7:43 pm
by Carl
Thanks Radu. But when I try adding the label "Related topics" using the <desc> tag, it doesn't work. In my WebHelp output, the <desc> string is ignored and now there's no "Related" title showing. Only the links to the related topics are shown.

I'd like to try the CSS method, but I don't know where to begin.

Re: Where are these related topic links coming from?

Posted: Mon May 27, 2019 1:53 pm
by Radu
Hi Carl,

Sorry about that, the <linklist><desc> approach does not seem to properly work with our WebHelp output. I added an issue to investigate this on our side.

So let's try this approach:

1) In the DITA topic you have a related link at the end (to a concept file):

Code: Select all

<related-links>
        <link href="../concepts/springFlowers.dita"/>
    </related-links>
2) The generated WebHelp output looks like this:

Code: Select all

<div class=" wh_related_links "><nav role="navigation" class="related-links">
                            <div class="linklist relinfo relconcepts"><strong>Related concepts</strong>
                            ............
3) I create a "custom.css" somewhere on my disk with this content:

Code: Select all

.related-links > .relinfo > strong {
    display:none;
}

.related-links > .relinfo:before {
    content: "Related topics: ";
    font-weight:bold;
}
4) Edit the transformation scenario you are using for publishing in Oxygen, in the "Parameters" tab set the "args.copy.css" parameter to "yes" and the parameter "args.css" to point to the custom.css.

5) Publish using the modified transformation scenario.

Regards,
Radu

Re: Where are these related topic links coming from?

Posted: Mon May 27, 2019 7:49 pm
by Carl
That worked!

Thank you very much, Radu.

Re: Where are these related topic links coming from?

Posted: Thu Jun 13, 2019 11:52 pm
by Carl
Hey Radu.

I just discovered a side effect glitch: if my Related Topics links go to both Concepts and Tasks, I end up getting two "Related topics" sections! For example:
Related topic:
Concept Topic

Related topic:
Task Topic
Is there any way to force it to put both under the same "Related topic" heading?

Re: Where are these related topic links coming from?

Posted: Fri Jun 21, 2019 10:23 am
by Radu
Hi Carl,

Sorry for the delay. Indeed by default the publishing engine splits the related links based on the target topic types.
I found something like this helps:

Code: Select all

    <related-links type="topic">
        <link href="summerFlowers.dita"/>
        <link href="../tasks/pruning.dita"/>
    </related-links>
so forcefully treating all links as generic topics by setting the @type attribute on the related links element.
This might interfere with the custom CSS fix I gave you so it needs to be tested with the CSS fix disabled first.

Regards,
Radu

Re: Where are these related topic links coming from?

Posted: Thu Jul 11, 2019 7:01 pm
by Carl
Hi Radu.

I am revisiting your reply above, as I thought I got rid of the problem but now it's reappeared in my project again. I don't understand this sentence from your reply:

Code: Select all

so forcefully treating all links as generic topics by setting the @type attribute on the related links element
I don't see a "@type" attribute in the related links element.

I have this code snippet:

Code: Select all

	<related-links props="pdf-hide">
		<link href="../_reuse/customize_business_metadata.dita"/>
		<link href="../_reuse/inspect_modify_json.dita"/>
	</related-links>
My topic "customize_business_metadata" is a Concept, while "inspect_modify_json" is a Task. I end up with two "Related topics" sections, one for each topic type. How should I tweak this to make them appear under a single "Related topics" heading? For now, my workaround is to convert the Task topic to a Concept.

Re: Where are these related topic links coming from?

Posted: Fri Jul 12, 2019 1:46 pm
by Radu
Hi,

I think my suggestion was to add the @type attribute on the related-links element, something like:

Code: Select all

    <related-links props="pdf-hide" type="topic">
        <link href="../_reuse/customize_business_metadata.dita"/>
        <link href="../_reuse/inspect_modify_json.dita"/>
    </related-links>
Regards,
Radu