Customized map schema: navtitles not resolved

[Frank Ralf]

Hi,

I'm working on a DITA map customization using RELAX NG, mainly stripping down the allowed elements. My sample maps validate against my schema and the transformations also work. However, the DITA Maps Manager doesn't show the titles of the referenced topics and ignores the following @navtitle altogether. The glossary navtitle also doesn't show in the generated PDF output.

Code: Select all

<map>

 ...

   <topichead navtitle="Glossary">

     <topicref keys="g_project" href="g_project.dita"/>

   </topichead>

  ...

</map>

I suppose there's something missing from my customization (e.g. some default attributes)? Any pointers welcome.

TIA
Frank

[Radu]

Hi Frank,

The DITA RNG schemas which come with the DITA OT bundled with Oxygen seem to properly work in these cases.

If you're saying that:

The glossary navtitle also doesn't show in the generated PDF output.

This would mean that probably the default @class attribute value + map/topicref mapgroup-d/topichead is not properly picked up for a topichead from the RNG schema.
For example if you open the DITA Map in the main editing area and you place the caret on the topichead element, the Attributes view should also show you the default attribute values it detected in the schema.

About the plain topicref titles not shown in the DITA Maps Manager, probably you forgot to define the default required attribute DITAArchVersion on the topic root element. The topic root element should also have the default attribute @domains defined on it.

Regards,
Radu

[Frank Ralf]

Hi Radu,

Thanks for your quick reply.

The DITA RNG schemas which come with the DITA OT bundled with Oxygen seem to properly work in these cases.

Yes, they do. I've checked my test files against the default DITA RNG schemas and everything is fine. Sorry for not mentioning this in the first place.

Many thanks for the pointers. I will check whether all required default attributes are set. I suppose that this might indeed be the cause of the issue because I started with the very restricted Lightweight DITA RNG implementation as a base for my customization. I will report back.

Kind regards,
Frank

[Frank Ralf]

You set me on the right track, Radu. Thanks again!

I've also noticed that DITA Maps Manager doesn't seem to resolve the <navtitle> of my opened map, neither with a (standard) DTD or RNG schema but I suppose this is by design, isn't it?

Kind regards,
Frank

[Frank Ralf]

Another thing: Keys defined in a map resolve correctly but don't show the "Keywords:" label in Author mode. I suppose this has also to do with missing or wrong default attributes?

Kind regards,
Frank

[Radu]

Hi Frank,

I've also noticed that DITA Maps Manager doesn't seem to resolve the <navtitle> of my opened map, neither with a (standard) DTD or RNG schema but I suppose this is by design, isn't it?

We usually present the map title if it appears either as a @title attribute on the map root element or as the <title> element first child inside the <map> element.
I'm not sure what the purpose of a <navtitle> defined in the <topicmeta> on a <map> element is. Could you elaborate on this?

Regards,
Radu

[Frank Ralf]

Hi Radu,

Thanks for your quick reply.

I'm not sure what the purpose of a <navtitle> defined in the <topicmeta> on a <map> element is. Could you elaborate on this?

I got this idea from Lightweight DITA and Michael Priestley's presentation at tcworld conference 2014 "Does DITA need XML?":

Simplify content models
- Only one way to specify title: as <navtitle> in <topicmeta>

But come to think of it, I don't see the rationale for this at first glance either

Kind regards,
Frank

[Radu]

Hi Frank,

Possibly LWDita intends to completely removed from the DITA Map schemas the possibility to set the title using the title element or the title attribute in order to simplify the vocabulary.

Regards,
Radu

[Radu]

Hi Frank,

About this question:

Keys defined in a map resolve correctly but don't show the "Keywords:" label in Author mode. I suppose this has also to do with missing or wrong default attributes?

Do you mean that you opened the DITA Map in the main editing area in the Author visual editing mode?
Possibly indeed the keywords element is missing a default @class attribute value or has an incorrect class attribute value specified on it.

Regards,
Radu

[Frank Ralf]

Hi,

Just some preliminary results. Besides missing the "Keywords:" label I was also missing the input field for the @keys attribute of <keydef> elements in Author mode. I got the input field back by the following changes:

• 1) There was a typo in the default value of the @class attribute: "mapgropup-d/keydef" instead of "mapgroup-d/keydef" which I had copied from the DITA specs.
  2) In addition, I also had to add the @processing-role="resource-only" attribute for the input field to show up.

Cheers,
Frank

[Frank Ralf]

Missing "Keywords" label

Possibly indeed the keywords element is missing a default @class attribute value or has an incorrect class attribute value specified on it.

I've had defined the correct class attribute for <keywords> but due to a typo I had referenced the attributes for <keyword> instead of the correct ones for the <keywords> element

So now also the labels are back. Only the topicrefs in DITA Maps Manager still don't pick up the navtitles. I'll keep you posted

Kind regards,
Frank

[Frank Ralf]

Topicrefs not resolved in DITA Maps Manager

Hi,

I think I finally found the culprit.

About the plain topicref titles not shown in the DITA Maps Manager, probably you forgot to define the default required attribute DITAArchVersion on the topic root element. The topic root element should also have the default attribute @domains defined on it.

Even after adding all the required default attributes to the topic root elements, the topicrefs still were not resolved. So I had a closer look at the <topicref> elements in the map itself and found that somehow the @locktitle attribute was set to the default value "yes". Changing this made the <navtitle>s appear in the DITA Maps Manager.

Many thanks again for your help and pointers.

Kind regards,
Frank

[Radu]

Hi Frank,

Right, the specs says something like:

If locktitle is set to "yes", the <navtitle> element or @navtitle attribute is used if it is present. Otherwise, the navtitle is ignored and the navigation title is retrieved from the referenced file.

Regards,
Radu

[Frank Ralf]

JFTR, here's the complete relevant part of the DITA spec:

If locktitle is set to "yes", the <navtitle> element or @navtitle attribute is used if it is present. Otherwise, the navtitle is ignored and the navigation title is retrieved from the referenced file.

yes
The navtitle in the map is used.
no
The navtitle or title of the topic is used. This is the processing default.

http://docs.oasis-open.org/dita/v1.2/os ... -atts.html

[Radu]

Hi Frank,

I will probably try to make some small changes to the DITA Maps Manager view to display the title detected from the topic if there is no navigation title available even if the locktitle attribute is set to yes.

Regards,
Radu

[Frank Ralf]

Hi Radu,

That sounds great. However, this was a good exercise to spot the error in our customization - and to learn more of the inner workings of DITA

Best regards,
Frank

[Radu]

Hi,

Just to update the thread, about this remark:

I will probably try to make some small changes to the DITA Maps Manager view to display the title detected from the topic if there is no navigation title available even if the locktitle attribute is set to yes.

it should work as stated in Oxygen 17.

Regards,
Radu

[Frank Ralf]

Hi Radu,

Thanks for the update. I will be on the lookout when giving oXygen 17 a try

Cheers,
Frank