Topics

Adding "next topic", "previous topic" throughout an entire map? #HTML #linking

Chris Papademetrious
 

Hi all,

I've embarrassingly spent half a day trying to figure this out! For the DITA-OT html5 transformation, is there a way to add "next topic" and "previous topic" links throughout the entire map, such that the map can be traversed from beginning to end using them?

The use case is that when we run FrameMaker-to-DITA conversion, the writers must step through every topic to evaluate whether the chunking is acceptable. I've been looking through XSLT code trying to figure out how to do this with existing parameters, but to no avail.

 - Chris

Kristen James Eberlein
 

Set collection-type="sequence" on the <map> element.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 1/13/2020 1:40 PM, Chris Papademetrious wrote:
Hi all,

I've embarrassingly spent half a day trying to figure this out! For the DITA-OT html5 transformation, is there a way to add "next topic" and "previous topic" links throughout the entire map, such that the map can be traversed from beginning to end using them?

The use case is that when we run FrameMaker-to-DITA conversion, the writers must step through every topic to evaluate whether the chunking is acceptable. I've been looking through XSLT code trying to figure out how to do this with existing parameters, but to no avail.

 - Chris

Chris Papademetrious
 

Indeed, that was embarrassingly easy!

However, there might be a bug. When I make the entire map a collection sequence:

<map collection-type="sequence">
  <title>This Book</title>

  <topicref href="t1/topic0.dita">
    <topicref href="t1/topic1.dita"/>
    <topicref href="t1/topic2.dita"/>  <!-- this one has no Next Topic link -->
  </topicref>

  <topicref href="t2/topic0.dita">
    <topicref href="t2/topic1.dita"/>
    <topicref href="t2/topic2.dita"/>
  </topicref>

  <topicref href="t3/topic0.dita">
    <topicref href="t3/topic1.dita"/>
    <topicref href="t3/topic2.dita"/>
  </topicref>

</map>

then the highlighted topic has no "Next Topic" link to the next top-level topic reference. Since all of these top-level topic references fall under the same collection sequence, navigation should continue throughout the sequence.

Is there some special case for top-level topic elements to be excluded from collection-sequence processing? If not, I'll file a DITA-OT issue for this.

Thank you!

 - Chris

Radu Coravu
 

Hi Chris,

This might not be a bug, the DITA 1.3 specs for collection-type seems to always use the notion of "children":

https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/ditamap-attributes.html

so the attribute seems to only add links between siblings and not between a topic and the sibling of its parent element.

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 1/14/2020 4:25 PM, Chris Papademetrious wrote:
Indeed, that was embarrassingly easy!
However, there might be a bug. When I make the entire map a collection sequence:
<map collection-type="sequence">
  <title>This Book</title>
  <topicref href="t1/topic0.dita">
    <topicref href="t1/topic1.dita"/>
    <topicref href="t1/topic2.dita"/>  <!-- this one has no Next Topic link -->
  </topicref>
  <topicref href="t2/topic0.dita">
    <topicref href="t2/topic1.dita"/>
    <topicref href="t2/topic2.dita"/>
  </topicref>
  <topicref href="t3/topic0.dita">
    <topicref href="t3/topic1.dita"/>
    <topicref href="t3/topic2.dita"/>
  </topicref>
</map>
then the highlighted topic has no "Next Topic" link to the next top-level topic reference. Since all of these top-level topic references fall under the same collection sequence, navigation should continue throughout the sequence.
Is there some special case for top-level topic elements to be excluded from collection-sequence processing? If not, I'll file a DITA-OT issue for this.
Thank you!
 - Chris

Lief Erickson
 

Hi Chris--

I ran into this issue with a few years ago with previous project but never did find a solution (I didn't dig too deep though either). I just took a look at the oXygen documentation[1] and noticed that it has the functionality that you want. Since the user guide is hosted on GitHub[2] I looked at the source and I noticed that @collection-type="sequence" is on the <bookmap> element and every <chapter> element. I generated HTML5 output and there were next/previous links for every page -- just as you want. I then removed every @collection-type="sequence" except the one from <bookmap>. Same result. There were next/prev links on every page. Thinking it might be an issue with <bookmap> versus <map> processing (who knows!) I made a valid <map> with <topicref> out of the oXygen user guide and regenerated. Still produced next/prev. links.

I don't know what it would be but maybe there's something in your environment? If nothing else, the oXygen user guide project might give you a hint.


On Fri, Jan 17, 2020 at 6:51 AM Radu Coravu <radu_coravu@...> wrote:
Hi Chris,

This might not be a bug, the DITA 1.3 specs for collection-type seems to
always use the notion of "children":

https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/ditamap-attributes.html

so the attribute seems to only add links between siblings and not
between a topic and the sibling of its parent element.

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 1/14/2020 4:25 PM, Chris Papademetrious wrote:
> Indeed, that was embarrassingly easy!
>
> However, there might be a bug. When I make the entire map a collection
> sequence:
>
> <map collection-type="sequence">
>    <title>This Book</title>
>
>    <topicref href="t1/topic0.dita">
>      <topicref href="t1/topic1.dita"/>
>      <topicref href="t1/topic2.dita"/>  <!-- this one has no Next Topic
> link -->
>    </topicref>
>
>    <topicref href="t2/topic0.dita">
>      <topicref href="t2/topic1.dita"/>
>      <topicref href="t2/topic2.dita"/>
>    </topicref>
>
>    <topicref href="t3/topic0.dita">
>      <topicref href="t3/topic1.dita"/>
>      <topicref href="t3/topic2.dita"/>
>    </topicref>
>
> </map>
>
> then the highlighted topic has no "Next Topic" link to the next
> top-level topic reference. Since all of these top-level topic references
> fall under the same collection sequence, navigation should continue
> throughout the sequence.
>
> Is there some special case for top-level topic elements to be excluded
> from collection-sequence processing? If not, I'll file a DITA-OT issue
> for this.
>
> Thank you!
>
>   - Chris
>





Chris Papademetrious
 

Hi Lief,

Indeed, I noticed that Oxygen's WebHelp seems to implement this in the desired way!

This morning I could not reproduce what I posted earlier. I suspect those results were for multiple collection sequences in the map, not just at the map level.

So I reran with collection-type="sequence" applied *only* at the map level. I found that the behavior differs between DITA-OT 3.4 and Oxygen's DITA-OT:

DITA-OT 3.4:

<map collection-type="sequence">
  <title>This Book</title>
  <topicref href="t1/topic0.dita">  >---+
    <topicref href="t1/topic1.dita"/>   |
    <topicref href="t1/topic2.dita"/>   |
    <topicref href="t1/topic3.dita"/>   |
  </topicref>                           |
                                        |
  <topicref href="t2/topic0.dita">  <---+  >--+
    <topicref href="t2/topic1.dita"/>         |
    <topicref href="t2/topic2.dita"/>         |
    <topicref href="t2/topic3.dita"/>         |
  </topicref>                                 |
                                              |
  <topicref href="t3/topic0.dita">  <---------+
    <topicref href="t3/topic1.dita"/>
    <topicref href="t3/topic2.dita"/>   
    <topicref href="t3/topic3.dita"/>
  </topicref>
</map>


Oxygen's DITA-OT:

<map collection-type="sequence">
  <title>This Book</title>
  <topicref href="t1/topic0.dita">  >-------+
    <topicref href="t1/topic1.dita"/>  <----+
    <topicref href="t1/topic2.dita"/>
    <topicref href="t1/topic3.dita"/>
  </topicref>
  <topicref href="t2/topic0.dita">  >-------+
    <topicref href="t2/topic1.dita"/>  <----+
    <topicref href="t2/topic2.dita"/>
    <topicref href="t2/topic3.dita"/>
  </topicref>
  <topicref href="t3/topic0.dita">  >-------+
    <topicref href="t3/topic1.dita"/>  <----+
    <topicref href="t3/topic2.dita"/>
    <topicref href="t3/topic3.dita"/>
  </topicref>
</map>


Both results used plain 'html5' transforms with fresh installations and no plugins installed. I'm not quite sure what to make of this difference. Which is correct and which is incorrect?

(Neither seems "correct" to me, because both provide the user with a "Next topic" link that skips information.)

 - Chris