How can I treat a <mapref> as a level of TOC hierarchy?


Chris Papademetrious
 

Hi fellow DITA users,

We are exploring Oxygen's WebHelp Responsive transformation, so I am exploring DITA-OT chunking to understand how to control the help structure.

I have multiple <bookmap> files referenced from a top-level <map>:

<map>
    <title>Online Help</title>
    <mapref href="book1.ditamap"/>
    <mapref href="book2.ditamap"/>
</map>

When I publish this (as WebHelp or as plain html5), the <bookmap> levels evaporate and I get a flat TOC of all book chapters:

  • Chapter 1
    • ...topics...
  • Chapter 2
    • ...topics...
  • Chapter 1
    • ...topics...
  • Chapter 2
    • ...topics...

But what I need is for each book to provide its own navigation level derived from its book title:

  • Book 1 Title
    • Chapter 1
      • ...topics...
    • Chapter 2
      • ...topics...
  • Book 2 Title
    • Chapter 1
      • ...topics...
    • Chapter 2
      • ...topics...

Wrapping each <mapref> in a <topichead> creates a level, but that approach doesn't inherit the book title. (Our books are conditional and often have conditional text, references to variables *within* the book scope, etc.).

I looked at the @chunk attribute documentation and experimented, and:

  • The to-navigation value sounds like what I need, but it is deprecated.
  • The to-content value did create a TOC level named after the book (hooray!), but proceeded to collapse the entire book's contents into a single flat topic (boo!).
  • Other values had no effect when applied to the <mapref> element. (Values set on a <bookmap> apply a policy to the entire map, which felt too intrusive to try.)

Books are big, important things. Hopefully there's a way to do this!

 - Chris


Chris Papademetrious
 

I'm attaching the tiny testcase I used for experimentation.

 - Chris


Dan Vint
 

I don't work with bookmarks but use map so I'm not sure of all the title derails. Sub maps do not interject structure and then don't introduce their own titles, they disappear as you have seen. The OT strip the map elements and chains them together during processing.

You had the right solution with the topic head, just make that the first element in your bookmap (if allowed). Put a simple title on the bookmap itself and make the text of your topchead contain the conditions to make the correct title.



Sent from my Verizon, Samsung Galaxy smartphone


-------- Original message --------
From: Chris Papademetrious <chrispitude@...>
Date: 6/19/21 7:41 AM (GMT-08:00)
To: main@dita-users.groups.io
Subject: [dita-users] How can I treat a as a level of TOC hierarchy?

Hi fellow DITA users,

We are exploring Oxygen's WebHelp Responsive transformation, so I am exploring DITA-OT chunking to understand how to control the help structure.

I have multiple <bookmap> files referenced from a top-level <map>:

<map>
    <title>Online Help</title>
    <mapref href="book1.ditamap"/>
    <mapref href="book2.ditamap"/>
</map>

When I publish this (as WebHelp or as plain html5), the <bookmap> levels evaporate and I get a flat TOC of all book chapters:

  • Chapter 1
    • ...topics...
  • Chapter 2
    • ...topics...
  • Chapter 1
    • ...topics...
  • Chapter 2
    • ...topics...

But what I need is for each book to provide its own navigation level derived from its book title:

  • Book 1 Title
    • Chapter 1
      • ...topics...
    • Chapter 2
      • ...topics...
  • Book 2 Title
    • Chapter 1
      • ...topics...
    • Chapter 2
      • ...topics...

Wrapping each <mapref> in a <topichead> creates a level, but that approach doesn't inherit the book title. (Our books are conditional and often have conditional text, references to variables *within* the book scope, etc.).

I looked at the @chunk attribute documentation and experimented, and:

  • The to-navigation value sounds like what I need, but it is deprecated.
  • The to-content value did create a TOC level named after the book (hooray!), but proceeded to collapse the entire book's contents into a single flat topic (boo!).
  • Other values had no effect when applied to the <mapref> element. (Values set on a <bookmap> apply a policy to the entire map, which felt too intrusive to try.)

Books are big, important things. Hopefully there's a way to do this!

 - Chris


Lionel Moizeau
 

Hey Chris,

What about using topicheads as a parent to the mapref?

Lionel


Le sam. 19 juin 2021 à 17:05, Dan Vint <dvint@...> a écrit :
I don't work with bookmarks but use map so I'm not sure of all the title derails. Sub maps do not interject structure and then don't introduce their own titles, they disappear as you have seen. The OT strip the map elements and chains them together during processing.

You had the right solution with the topic head, just make that the first element in your bookmap (if allowed). Put a simple title on the bookmap itself and make the text of your topchead contain the conditions to make the correct title.



Sent from my Verizon, Samsung Galaxy smartphone


-------- Original message --------
From: Chris Papademetrious <chrispitude@...>
Date: 6/19/21 7:41 AM (GMT-08:00)
Subject: [dita-users] How can I treat a as a level of TOC hierarchy?

Hi fellow DITA users,

We are exploring Oxygen's WebHelp Responsive transformation, so I am exploring DITA-OT chunking to understand how to control the help structure.

I have multiple <bookmap> files referenced from a top-level <map>:

<map>
    <title>Online Help</title>
    <mapref href="book1.ditamap"/>
    <mapref href="book2.ditamap"/>
</map>

When I publish this (as WebHelp or as plain html5), the <bookmap> levels evaporate and I get a flat TOC of all book chapters:

  • Chapter 1
    • ...topics...
  • Chapter 2
    • ...topics...
  • Chapter 1
    • ...topics...
  • Chapter 2
    • ...topics...

But what I need is for each book to provide its own navigation level derived from its book title:

  • Book 1 Title
    • Chapter 1
      • ...topics...
    • Chapter 2
      • ...topics...
  • Book 2 Title
    • Chapter 1
      • ...topics...
    • Chapter 2
      • ...topics...

Wrapping each <mapref> in a <topichead> creates a level, but that approach doesn't inherit the book title. (Our books are conditional and often have conditional text, references to variables *within* the book scope, etc.).

I looked at the @chunk attribute documentation and experimented, and:

  • The to-navigation value sounds like what I need, but it is deprecated.
  • The to-content value did create a TOC level named after the book (hooray!), but proceeded to collapse the entire book's contents into a single flat topic (boo!).
  • Other values had no effect when applied to the <mapref> element. (Values set on a <bookmap> apply a policy to the entire map, which felt too intrusive to try.)

Books are big, important things. Hopefully there's a way to do this!

 - Chris


Chris Papademetrious
 

Hi Dan,

Thanks for the suggestion! I can't use <topichead> directly in the <bookmap> because

  • A <bookmap> does not permit <topichead> at its top level, only <chapter>, <appendix>, and other book-like things.
  • Even if allowed, it would add a level to the book's TOC when the book PDF is published.

Hi Lionel,

Thanks also for the suggestion! I can wrap each <mapref> in a <topichead>, but that doesn't allow me to use the book's intrinsic title as the title for that level.

As a last resort, I could variable-ize each book's title, then reach into each book's scope to get that variable, but I'm hoping to find a better way (because that would require me to modify hundreds of books).

 - Chris


ekimber@contrext.com
 

As others have pointed out, the titles of submaps are not retained and do not contributed to the title hierarchy of the result document.

 

This seems to be a common misunderstanding and it’s easy to see why people might naturally assume that subtopic titles will contribute to the publication’s title hierarchy, but nevertheless they do not.

 

[NOTE: If your PDF generation process treats submap titles as part of the publication title hierarchy *it is doing the wrong thing*. Submap titles are metadata and should *never* contribute to the publication title hierarchy because to do so is to create an serious incompatibility with normal DITA processing. In this case, your data is incorrectly structured and needs to be fixed. Of course, if you’re in this situation you may not be in a position to correct the data, but do understand that your data is not correct and really needs to be fixed. At a minimum, the PDF generation code should have a very prominent comment somewhere that it is treating submap titles as though they were topic heads as a *workaround* to a data problem.]

 

Note that by “topichead” we don’t mean “the <topichead> element”, we mean “A topicref of any type that does not refer to a resource (no @href or @keyref) and has a <navtitle>”. Any specialization of topicref that is not explicitly set to a processing role of “resource-only” should able to function as a topichead as long as it allows <topicmeta> and <navtitle> and does not also require @href or @keyref. So <keydef> cannot be a topichead (because it is explicitly resource-only) but all the topicref specializations in bookmap can be.

 

This means you can create a topichead using <chapter> in <bookmap>

 

<bookmap>

  <bookmeta>

   …

</bookmeta>

 

<chapter>

  <topicmeta>

     <navtitle>Installation</navtitle>

   </topicmeta>

   <mapref href=”install-chapter-topics.ditamap”/>

</chapter>

</bookmap>

 

This works and should produce a result identical to having a reference to a title-only topic for PDF output.

 

However, for HTML output you get different behaviors for topicheads and title-only topics—you definitely see this in Open Toolkit’s HTML transforms—a topichead is reflected in the ToC but does not get its own HTML page.

 

 

 

--

Eliot Kimber

http://contrext.com

 

 

 

From: <main@dita-users.groups.io> on behalf of Chris Papademetrious <chrispitude@...>
Reply-To: <main@dita-users.groups.io>
Date: Saturday, June 19, 2021 at 11:37 AM
To: <main@dita-users.groups.io>
Subject: Re: [dita-users] How can I treat a <mapref> as a level of TOC hierarchy?

 

Hi Dan,

Thanks for the suggestion! I can't use <topichead> directly in the <bookmap> because

  • A <bookmap> does not permit <topichead> at its top level, only <chapter>, <appendix>, and other book-like things.
  • Even if allowed, it would add a level to the book's TOC when the book PDF is published.


Hi Lionel,

Thanks also for the suggestion! I can wrap each <mapref> in a <topichead>, but that doesn't allow me to use the book's intrinsic title as the title for that level.

As a last resort, I could variable-ize each book's title, then reach into each book's scope to get that variable, but I'm hoping to find a better way (because that would require me to modify hundreds of books).

 - Chris


Chris Papademetrious
 

Hi Eliot,

As always, thanks for jumping in!

We use SyncroSoft's PDF Chemistry for PDF publishing. And it behaves correctly - it doesn't create navigation hierarchy from submap titles. My previous comment was that topichead levels added inside a <bookmap> would alter the book PDF's TOC, so modifying the <bookmap> is not an option.

However, your mention of <navtitle> within <topicmeta> pointed me in the right direction! I get the desired result by variable-izing the book titles, then creating a top-level map as follows:

<map>
    <title>Online Help</title>

    <topichead>

      <topicmeta>
        <navtitle><ph keyref="book1.BookTitle"/></navtitle>
      </topicmeta>
      <mapref href="book1.ditamap" format="ditamap" keyscope="book1"/>
    </topichead>

    <topichead>

      <topicmeta>
        <navtitle><ph keyref="book2.BookTitle"/></navtitle>
      </topicmeta>
      <mapref href="book2.ditamap" format="ditamap" keyscope="book2"/>
    </topichead>

</map>


When I publish this map (either with the DITA-OT's html5 transformation or with Oxygen's WebHelp Responsive transformation), each book has its own hierarchy item, named after the book title. Success!

With this success under my belt, I started poking around in the preprocess2 pipeline to see if I could automate the creation of these <topichead>/<navtitle>/<mapref> constructs with a user-specified attribute as a convenience:

      <mapref href="book1.ditamap" format="ditamap" keyscope="book1" outputclass="topichead"/>
      <mapref href="book2.ditamap" format="ditamap" keyscope="book2" outputclass="topichead"/>

It is achievable, but there are some complexities with ensuring that book titles with profiling conditions and book-local variables are handled properly. I might keep at it just to learn more about the processing pipeline. But for production, I think it's better to stick with pure DITA without adding yet another plugin dependency.

 - Chris


Chris Papademetrious
 

Hi everyone,

I created a plugin that can automatically add navigation hierarchy for submaps:

https://github.com/chrispy-snps/DITA-mapref-topichead

 - Chris


ekimber@contrext.com
 

If these submaps are individual publications and are also used as root maps in their own right then I would be tempted to refer to them as peer-scoped resources and have that trigger the preprocessing you’re using. Alternatively you could refactor the maps so you have one root map just for standalone publication and another for this combined publication use and use either submaps or conref from the root maps to pull in the parts. That would be painful and ugly, but it would work.

 

The semantic of scope=”peer” on map references is “this is a separate root map”, which is I think the semantic you have here, even though you’re publishing them as a single HTML result.  You could just as easily publish them independently to the same parent location and get the same effect as long as you had a way to construct the top-level navigation over the otherwise-independent publications being published together.

 

It looks like I made a bad assumption about your use case—I had assumed that you had submaps used from a root bookmap where you were expecting the submap titles to contribute to the book’s title hierarchy—I’ve just had that case in a client’s content so that case was fresh in my mind (and I’ve seen it before—as I said it’s not a crazy assumption to make that submaps would work that way so it’s not surprising that people do it).

 

So I think you’ve shown a general requirement for an HTML publishing process that can publish a set of otherwise-independent publications together, either as a single publishing action or as multiple publishing actions where the results are coordinated so the final published result is correct. For example, I might have a system that can use the map you show (with scope=”peer” on the mapsrefs) to generate the top-level navigation over the books and then publish each book separately under this navigation parent so that, once published, all the navigation works.

 

I also noticed that you’ve put @keyscope on the <mapref> but I don’t think that’s what you want, because if those are bookmaps, they don’t have a single root topicref to act as the key scope root (although Open Toolkit will synthesize a <topicgroup> for the map and put the keyscope on that, so I guess it’ s OK, at least there), but I would put the @keyscope on the topicheads, as those become the root topicrefs for each publication:

 

    <topichead keyscope=”book1”>
      <topicmeta>
        <navtitle><ph keyref="book1.BookTitle"/></navtitle>
      </topicmeta>
      <mapref href="book1.ditamap" format="ditamap"/>
    </topichead>

    <topichead keyscope="book2">

      <topicmeta>
        <navtitle><ph keyref="book2.BookTitle"/></navtitle>
      </topicmeta>
      <mapref href="book2.ditamap" format="ditamap"/>
    </topichead>

It’s important to remember that a mapref is really a reference to the topicrefs contained by the referenced map, so if the map you’re referencing doesn’t itself have a single root topicref, the merged result will not either, thus the need to add the topiceheads you have here (or you could have referenced title-only topics if you preferred).

 

I think the BookMap design might have been better if it had used a required root topicref to represent the publication root and hold the publication-level title and metadata. That design would have avoided this problem entirely, but that ship has long sailed and I didn’t even take that route in my DITA for Publishers PublicationMap design (although I should have, I now realize).

 

Cheers,

 

Eliot

 

--

Eliot Kimber

http://contrext.com

 

 

 

From: <main@dita-users.groups.io> on behalf of Chris Papademetrious <chrispitude@...>
Reply-To: <main@dita-users.groups.io>
Date: Saturday, June 19, 2021 at 3:59 PM
To: <main@dita-users.groups.io>
Subject: Re: [dita-users] How can I treat a <mapref> as a level of TOC hierarchy?

 

Hi Eliot,

As always, thanks for jumping in!

We use SyncroSoft's PDF Chemistry for PDF publishing. And it behaves correctly - it doesn't create navigation hierarchy from submap titles. My previous comment was that topichead levels added inside a <bookmap> would alter the book PDF's TOC, so modifying the <bookmap> is not an option.

However, your mention of <navtitle> within <topicmeta> pointed me in the right direction! I get the desired result by variable-izing the book titles, then creating a top-level map as follows:

<map>
    <title>Online Help</title>

    <topichead>

      <topicmeta>
        <navtitle><ph keyref="book1.BookTitle"/></navtitle>
      </topicmeta>
      <mapref href="book1.ditamap" format="ditamap" keyscope="book1"/>
    </topichead>

    <topichead>

      <topicmeta>
        <navtitle><ph keyref="book2.BookTitle"/></navtitle>
      </topicmeta>
      <mapref href="book2.ditamap" format="ditamap" keyscope="book2"/>
    </topichead>

</map>


When I publish this map (either with the DITA-OT's html5 transformation or with Oxygen's WebHelp Responsive transformation), each book has its own hierarchy item, named after the book title. Success!

With this success under my belt, I started poking around in the preprocess2 pipeline to see if I could automate the creation of these <topichead>/<navtitle>/<mapref> constructs with a user-specified attribute as a convenience:

      <mapref href="book1.ditamap" format="ditamap" keyscope="book1" outputclass="topichead"/>
      <mapref href="book2.ditamap" format="ditamap" keyscope="book2" outputclass="topichead"/>

It is achievable, but there are some complexities with ensuring that book titles with profiling conditions and book-local variables are handled properly. I might keep at it just to learn more about the processing pipeline. But for production, I think it's better to stick with pure DITA without adding yet another plugin dependency.

 - Chris


ekimber@contrext.com
 

I just realized that in the example, by putting the keyscopes on the topicheads, you can remove the keyscope qualification from the keyrefs on the <ph> elements in the navigation titles, further simplifying the markup.

 

Cheers,

 

E.

 

--

Eliot Kimber

http://contrext.com

 

 

 

From: <main@dita-users.groups.io> on behalf of "ekimber@..." <ekimber@...>
Reply-To: <main@dita-users.groups.io>
Date: Sunday, June 20, 2021 at 9:44 AM
To: <main@dita-users.groups.io>
Subject: Re: [dita-users] How can I treat a <mapref> as a level of TOC hierarchy?

 

If these submaps are individual publications and are also used as root maps in their own right then I would be tempted to refer to them as peer-scoped resources and have that trigger the preprocessing you’re using. Alternatively you could refactor the maps so you have one root map just for standalone publication and another for this combined publication use and use either submaps or conref from the root maps to pull in the parts. That would be painful and ugly, but it would work.

 

The semantic of scope=”peer” on map references is “this is a separate root map”, which is I think the semantic you have here, even though you’re publishing them as a single HTML result.  You could just as easily publish them independently to the same parent location and get the same effect as long as you had a way to construct the top-level navigation over the otherwise-independent publications being published together.

 

It looks like I made a bad assumption about your use case—I had assumed that you had submaps used from a root bookmap where you were expecting the submap titles to contribute to the book’s title hierarchy—I’ve just had that case in a client’s content so that case was fresh in my mind (and I’ve seen it before—as I said it’s not a crazy assumption to make that submaps would work that way so it’s not surprising that people do it).

 

So I think you’ve shown a general requirement for an HTML publishing process that can publish a set of otherwise-independent publications together, either as a single publishing action or as multiple publishing actions where the results are coordinated so the final published result is correct. For example, I might have a system that can use the map you show (with scope=”peer” on the mapsrefs) to generate the top-level navigation over the books and then publish each book separately under this navigation parent so that, once published, all the navigation works.

 

I also noticed that you’ve put @keyscope on the <mapref> but I don’t think that’s what you want, because if those are bookmaps, they don’t have a single root topicref to act as the key scope root (although Open Toolkit will synthesize a <topicgroup> for the map and put the keyscope on that, so I guess it’ s OK, at least there), but I would put the @keyscope on the topicheads, as those become the root topicrefs for each publication:

 

    <topichead keyscope=”book1”>
      <topicmeta>
        <navtitle><ph keyref="book1.BookTitle"/></navtitle>
      </topicmeta>
      <mapref href="book1.ditamap" format="ditamap"/>
    </topichead>

    <topichead keyscope="book2">

      <topicmeta>
        <navtitle><ph keyref="book2.BookTitle"/></navtitle>
      </topicmeta>
      <mapref href="book2.ditamap" format="ditamap"/>
    </topichead>


It’s important to remember that a mapref is really a reference to the topicrefs contained by the referenced map, so if the map you’re referencing doesn’t itself have a single root topicref, the merged result will not either, thus the need to add the topiceheads you have here (or you could have referenced title-only topics if you preferred).

 

I think the BookMap design might have been better if it had used a required root topicref to represent the publication root and hold the publication-level title and metadata. That design would have avoided this problem entirely, but that ship has long sailed and I didn’t even take that route in my DITA for Publishers PublicationMap design (although I should have, I now realize).

 

Cheers,

 

Eliot

 

--

Eliot Kimber

http://contrext.com

 

 

 

From: <main@dita-users.groups.io> on behalf of Chris Papademetrious <chrispitude@...>
Reply-To: <main@dita-users.groups.io>
Date: Saturday, June 19, 2021 at 3:59 PM
To: <main@dita-users.groups.io>
Subject: Re: [dita-users] How can I treat a <mapref> as a level of TOC hierarchy?

 

Hi Eliot,

As always, thanks for jumping in!

We use SyncroSoft's PDF Chemistry for PDF publishing. And it behaves correctly - it doesn't create navigation hierarchy from submap titles. My previous comment was that topichead levels added inside a <bookmap> would alter the book PDF's TOC, so modifying the <bookmap> is not an option.

However, your mention of <navtitle> within <topicmeta> pointed me in the right direction! I get the desired result by variable-izing the book titles, then creating a top-level map as follows:

<map>
    <title>Online Help</title>

    <topichead>

      <topicmeta>
        <navtitle><ph keyref="book1.BookTitle"/></navtitle>
      </topicmeta>
      <mapref href="book1.ditamap" format="ditamap" keyscope="book1"/>
    </topichead>

    <topichead>

      <topicmeta>
        <navtitle><ph keyref="book2.BookTitle"/></navtitle>
      </topicmeta>
      <mapref href="book2.ditamap" format="ditamap" keyscope="book2"/>
    </topichead>

</map>


When I publish this map (either with the DITA-OT's html5 transformation or with Oxygen's WebHelp Responsive transformation), each book has its own hierarchy item, named after the book title. Success!

With this success under my belt, I started poking around in the preprocess2 pipeline to see if I could automate the creation of these <topichead>/<navtitle>/<mapref> constructs with a user-specified attribute as a convenience:

      <mapref href="book1.ditamap" format="ditamap" keyscope="book1" outputclass="topichead"/>
      <mapref href="book2.ditamap" format="ditamap" keyscope="book2" outputclass="topichead"/>

It is achievable, but there are some complexities with ensuring that book titles with profiling conditions and book-local variables are handled properly. I might keep at it just to learn more about the processing pipeline. But for production, I think it's better to stick with pure DITA without adding yet another plugin dependency.

 - Chris