Topics

Topichead usage and best practice #bookmap

Matt Lorenzi
 

We have a set of common chapter-level topics that are just used for heading purposes, i.e.: Inspection, Installation, Certification, etc.

I learned just recently that you can use <topichead> in a ditamap instead of a stand-alone DITA topic to serve the same purpose.

This is nice to know since it seems a bit odd to use a topic with just a <title> element in it. I suspect this method was used (before my time), as this was the only way we knew how to create a chapter heading, and to ensure consistent chapter headings throughout all our DITA documentation. 

So, if using <topichead>, can it be used in conjunction with keys? I would still like to ensure common usage for chapter headings where appropriate, and if a <topichead> wound need to be created for each ditamap I can see inconsistencies creeping in. How would I use <topichead> with keys/key refs?

Dan Vint
 

Topicheads in html output do not give you something you can link to, they are just organizational. You are probably having difficulties trying to define a key for them as they are not a topic or a map



Sent from my Verizon, Samsung Galaxy smartphone


-------- Original message --------
From: "Matt Lorenzi via groups.io" <mjlorenzi@...>
Date: 4/24/20 11:23 AM (GMT-08:00)
To: main@dita-users.groups.io
Subject: [dita-users] Topichead usage and best practice #bookmap

We have a set of common chapter-level topics that are just used for heading purposes, i.e.: Inspection, Installation, Certification, etc.

I learned just recently that you can use <topichead> in a ditamap instead of a stand-alone DITA topic to serve the same purpose.

This is nice to know since it seems a bit odd to use a topic with just a <title> element in it. I suspect this method was used (before my time), as this was the only way we knew how to create a chapter heading, and to ensure consistent chapter headings throughout all our DITA documentation. 

So, if using <topichead>, can it be used in conjunction with keys? I would still like to ensure common usage for chapter headings where appropriate, and if a <topichead> wound need to be created for each ditamap I can see inconsistencies creeping in. How would I use <topichead> with keys/key refs?

Matt Lorenzi
 

I'm a little confused, why would they exist then if you can't possibly link to them - unless it's for a PDF output scenario only? So is it best to avoid topichead if potentially outputting the map in both PDF and HTML (and you want to link to this heading)?

Dan Vint
 

Personally I like them in the toc when you really only want a heading. The draw back is they only exist in the toc so there is nothing to link to. You will see that the url does not change if you give it a try. But the toc will typically register expanding the content list nested within.

For me I see it keeping a writer from just generating random introductory text because you have no place to create content.

With that said, my company is on a seek and destroy mission to remove them. It didn't help our situation in a recent update where the toc didn't synch to the topic being displayed. That drew attention to this problem as well as having short introductory topics that said something to the effect of:

To do xxxx see the following topics.



Sent from my Verizon, Samsung Galaxy smartphone


-------- Original message --------
From: "Matt Lorenzi via groups.io" <mjlorenzi@...>
Date: 4/24/20 12:44 PM (GMT-08:00)
To: main@dita-users.groups.io
Subject: Re: [dita-users] Topichead usage and best practice #bookmap

I'm a little confused, why would they exist then if you can't possibly link to them - unless it's for a PDF output scenario only? So is it best to avoid topichead if potentially outputting the map in both PDF and HTML (and you want to link to this heading)?

ronny.flink@...
 

Hi,
I stopped using <topichead> after read the DITA style guide, by Tony Self. I also had problems with untranslated titles, when forgot to send <topichead> content to translation.

” There are two main reasons why topichead elements should be avoided. The first is that it conflicts with the notion of the separation of content and form, and the separation of data and metadata. All content (data) in a document should reside in the topics, not in the map. The ditamap should only contain metadata. If you use topichead as an alternative to a title-only topic, you are effectively placing non-reusable content, or data, in the ditamap. The second reason is more practical. If you are transforming a ditamap to a hypertext output format with a TOC, such as to Eclipse Help, the topichead elements will be transformed to unlinked parent nodes in the TOC. When the user clicks on such a node, the content pane will not display an associated topic, as it will for other nodes in the TOC. This inconsistency appears to the user to be an error. The unlinked node in the TOC will also cause inconsistencies or malfunctions in the way breadcrumbs function, and the way sequences (previous and next topic links) function.”


best regards
Ronny

Bill Burns
 

Ronny Flink write:

 

> I stopped using <topichead> after read the DITA style guide, by Tony Self. I also had problems with untranslated titles, when forgot to send <topichead> content to translation.

 

As with all such determinations, it depends (the consultants’ favorite response). I was always a strong proponent of using only the title and titlealts from the topic, in part, because it’s easier to maintain consistency in translation. That said, I have come across use cases in which different titles are needed depending on the type of deliverable—often more than just the single navigation title allows. The best way to handle them, for these use cases, was to use topicheads. In these cases the ONLY title being used was the navtitle in the topichead/topicmeta. Topic titles and any topic titlealts were ignored.

 

So my advice would be to determine what’s best for your use case and for maximum reuse.

 

Bill Burns

wdburns63@...

+1.208.794.5709

 

From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of ronny.flink@...
Sent: Monday, April 27, 2020 8:29 AM
To: main@dita-users.groups.io
Subject: Re: [dita-users] Topichead usage and best practice #bookmap

 

Hi,
I stopped using <topichead> after read the DITA style guide, by Tony Self. I also had problems with untranslated titles, when forgot to send <topichead> content to translation.

” There are two main reasons why topichead elements should be avoided. The first is that it conflicts with the notion of the separation of content and form, and the separation of data and metadata. All content (data) in a document should reside in the topics, not in the map. The ditamap should only contain metadata. If you use topichead as an alternative to a title-only topic, you are effectively placing non-reusable content, or data, in the ditamap. The second reason is more practical. If you are transforming a ditamap to a hypertext output format with a TOC, such as to Eclipse Help, the topichead elements will be transformed to unlinked parent nodes in the TOC. When the user clicks on such a node, the content pane will not display an associated topic, as it will for other nodes in the TOC. This inconsistency appears to the user to be an error. The unlinked node in the TOC will also cause inconsistencies or malfunctions in the way breadcrumbs function, and the way sequences (previous and next topic links) function.”


best regards
Ronny


Virus-free. www.avast.com

Bill Burns
 

That was obviously supposed to say “Ronny Flink wrote”—sheesh.

 

 


Virus-free. www.avast.com

Larry Kollar
 

My faulty memory about this thread prompted me, when someone at work asked about doing this, to suggest using a topicref with a navtitle and no href. Preliminary testing suggests it works. SDL's Publication Manager insists on an href, but we can open a map in Oxygen or Xmetal and add it there.

Joe Pairman
 

Thanks for sharing that! Tony provides a really good, succinct view there on why not to use topicheads as a general rule. 

The only time I used them in an IA was to drive a very specific output where the topic heads were non-selectable visual cues. Even so, I might be tempted to do it a different way if I had to do it again — something like a specialized outputclass attribute triggering custom stylesheet processing. 

On Mon, Apr 27, 2020 at 15:28 <ronny.flink@...> wrote:
Hi,
I stopped using <topichead> after read the DITA style guide, by Tony Self. I also had problems with untranslated titles, when forgot to send <topichead> content to translation.

” There are two main reasons why topichead elements should be avoided. The first is that it conflicts with the notion of the separation of content and form, and the separation of data and metadata. All content (data) in a document should reside in the topics, not in the map. The ditamap should only contain metadata. If you use topichead as an alternative to a title-only topic, you are effectively placing non-reusable content, or data, in the ditamap. The second reason is more practical. If you are transforming a ditamap to a hypertext output format with a TOC, such as to Eclipse Help, the topichead elements will be transformed to unlinked parent nodes in the TOC. When the user clicks on such a node, the content pane will not display an associated topic, as it will for other nodes in the TOC. This inconsistency appears to the user to be an error. The unlinked node in the TOC will also cause inconsistencies or malfunctions in the way breadcrumbs function, and the way sequences (previous and next topic links) function.”


best regards
Ronny