Re: keydef in bookmaps?

Dave C


I have been having a similar problem. I am trying to pass a part number and printing date from the bookmap to a static boiler.dita file. In some of my books it works fine every time, in others it fails every time, except for the first time it is run. On all the failing cases, I get the following error:

[pipeline] java.lang.NullPointerException
[pipeline] [DOTJ047I][INFO] Unable to find key definition for keyref="bookpartno", href may be used as fallback if it exists. Please make sure the key name is correct.
[pipeline] [DOTJ047I][INFO] Unable to find key definition for keyref="date", href may be used as fallback if it exists. Please make sure the key name is correct.

I have actually copied the entire <frontmatter> from a bookmap that always works and pasted it into a bookmap that always fails and there is no change in the outcome.

Any thoughts?

Dave C.

--- In, Eliot Kimber <ekimber@...> wrote:

On 1/15/10 3:48 AM, "nigelfrance" <nparker@...> wrote:

I'm trying to use conkeyref in conjunction with keydef/keys to provide an easy
method to use variable strings.

I have created a variables.xml topic that contains:

<topic id="id087ELM0405Z">
<title>Variable Definitions</title>
<p><ph id="familyname">Brand Name</ph></p>
<p><ph id="productname">My Product Version 1</ph></p>
<p><ph id="productnameshort">Product V1</ph></p>
You don't need conref just to get strings, you can put the strings in the
key definitions then use just the key. E.g., in a map document:

<keydef key="familyname">
<keyword>Brand Name</keyword>

And then in your topic:

<ph keyref="familyname"/>

I just tested this with the latest 1.5 Toolkit and it works.

But in any case, conrefs should work everywhere consistently--the Toolkit
does conref resolution before it does any other processing, meaning that the
final-stage transforms, the ones that produce a specific output, are given
data that reflects conref having already been resolved.

I reference this topic in a BOOKMAP's frontmatter as:

<keydef keys="variables" href="rVariables.xml"/>

From within *most* topics, I can include a variable with, for example:

<ph conkeyref="variables/productname"/>

This all works as expected.

However, within topics in the frontmatter of the BOOKMAP (ie the preface), the
variables are not being resolved and nothing appears in the output.

This sounds like a bug to me, but any ideas as to how to fix this ?
It's either bug or user error, although it's hard to imagine what the user
error could be.

One test would be to generate HTML and see if you get the same result. Also,
check the toolkit log to see if it says anything about unresolvable key

If you can put together a small failing test case I'll be happy to take a
look at it off list.



On 1/8/10 2:45 PM, "nigelfrance" <nparker@> wrote:

Hi Eliot,
Got it now, thanks.
Cool. The way you're using keys is one of the main use cases that drove the
key design, that is, replacing conref for getting variable or
context-dependent terms and phrases.

Note that if you add an @href to your keydef that points to e.g., a glossary
entry topic, then the <keyword> element will both reflect the keyword
defined in the keydef and be a navigable link to the target topic.



In my bookmap I have:

<topicref href="testkeys.ditamap" format="ditamap"/>

Where testkeys.ditamap contains:

<map title="DITA Topic Map">
<keydef keys="productname">
<keyword>My Product Version 1</keyword>
<keydef keys="shortproductname">
<keyword>My Prod V1</keyword>

To reference these keywords: overview of <keyword keyref="productname"/> (hereafter abbreviated to
<keyword keyref="shortproductname"/>).

Thanks again.

On 1/8/10 11:36 AM, "nigelfrance" <nparker@> wrote:

I can't, however, seem to get it to work when I put the keywords in a
file and use href:

<keydef href="testkeys.ditamap" keys="productname" format="ditamap"/>
This is your problem. You want to use a normal topicref to include the map,

<topicref href="testkeys.ditamap" format="ditamap"/>

Where testkeys.ditamap then contains the keydef for "productname" as from
your working example.

That is, you're pulling in a map that contains a set of key definitions,
using the map's metadata as the key definition.



and in testkeys.ditamap (seems I need a ditamap to get topicmeta, whereas
example was a .dita?):

<map title="DITA Topic Map">
<keyword>Product Name in DITAMAP</keyword>

In this case, there are no processing errors, but the keyword doesn't
in the output. What am I missing?

I sometimes use a lot of variables in a document and it seems like I'd
include a lot of markup, with keydef/topicmeta/keywords/keyword repeated
each variable. Using the external form, I'd have less markup in the
but would need to maintain a separate ditamap file for each keyword?

It would be nice to be able to do something like:

<keydef keys="productname" keyword="My Product Version 1"/>
<keydef keys="shortproductname" keyword="Product V1"/>

Is there any way to achieve this?

On 1/7/10 3:30 AM, "nigelfrance" <nparker@> wrote:

I notice that the keydef element that is new in DITA-OT1.5 is only
in ditamaps, not bookmaps. Was this a deliberate omission? Looks like a
feature and to me it would be just as useful in bookmaps as ditamaps.
You can use <keydef> in Bookmaps, just not as a direct child of
For example, you can have <keymap> within <frontmatter>.

Note that any topicref or topicref specialization should be able to
keys (unless the designer of the specialization has explicitly disallowed
they @keys attribute, which would be an odd thing to do).

The <keydef> element is just a convenience in that it sets the default
of the new attribute @processing-role to "resource-only", indicating that
<keydef> elements, by default, serve only to define keys and do not
contribute directly to the navigation hierarchy.

For example, this keydef element:


Is exactly equivalent to this topicref element:


Any topicref can define keys, so you can add keys to existing topicrefs
existing maps--you don't have to use new topicrefs just to define keys,
although that may be good practice for other reasons (such as making it
to find by inspection what keys have been defined in a given map).

In my map specializations I like to create a separate topicref
specialization named "keydefs" whose sole purpose is to hold <keydef>
elements for ease of organization.

One common practice is to put all key definitions into separate map
documents that contain only keydefs, and then include those key-defining
maps into main maps. This helps to keep key definitions concentrated in
place, making them easier to find and manage and possibly making it
for tools to manage keys more effectively.

When using keys, one authoring challenge is knowing what keys are
for use by key references. In the absence of a key-aware CMS or link
management system, putting all key definitions into separate maps with
well-known locations and/or naming conventions or into consistent places
within maps will go a long way toward making the use of keys more

Keep in mind too that there is an unavoidable processing challenge with
keys, which is that the same key name can be defined any number of times
within a map tree, but only the first one in a given map tree is
in a breadth-first traversal of the map tree.

This means you can't know what the set of available keys is or what the
effective definition of a given key is without first establishing a root
context, building the map tree, and constructing the "key space" for that
map tree.

While you would ultimately like to depend on tools to do this for you
authoring, in many cases authors will have to find keys by inspecting the
maps they are working with. Having key definitions scattered about the
makes it harder to do this manually. If all key definitions are collected
into consistent places within maps, authors can be reasonably certain
they've found the effective definition of a given key within a given map

Since one of the points of keys is that the same key name may have
bindings in different use contexts (different map trees), it would be
missing the point of keys to require that a given key name have exactly
definition in a given information set, so you can't rely on simple key

Depending on the nature of the information, another technique is to
the set of key names separately because the key names reflect the things
being documented, e.g., API class and method names, tagnames, part
or names, glossary terms, etc. That is, for a given information set there
may be a set of well-known and largely invariant key names that can be
defined and documented separate from the definition of those keys in
Authors then blindly use the keys in references, confident that someone
has taken care of creating the appropriate key definitions for different

Note that the DITA For Publishers project includes a general DITA link
management Java API and some command-line utilities built using that
library, including a "map bos report" tool that processes a root map and
reports all the files ultimately used from that map as well as the key
represented by that map (that is, the set of key effective key
and their bindings).

The package is available from the files area of the DITA4Publishers
on SourceForge:>>

The intent of this code is, in part, to enable more complete support for
keys in authoring tools by providing a general-purpose key management
facility. That is, the library provides the service of constructing and
providing access to key spaces and doing key resolution on demand. In
theory, by providing a public API for DITA-specific link management, it
would make it easier for DITA-aware authoring tools and processors to
integrate with DITA-aware content management and link management systems.
least that's the idea. In any case, I'm trying to lower the cost of using
keys and key references by providing some base infrastructure for
key-related processing.


Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770

Join to automatically receive all group messages.