Creating an index using an index.ditamap and conrefs

[xephon]

Hi,

I have a central DITA map containing all my indexterm elements.

index.ditamap

Code: Select all

<map>

  <title>Index</title>

  <topicmeta>

    <keywords>

      <indexterm id="Index_Foo">foo</indexterm>

	  ...

	</keywords>

  </topicmeta>

</map> 

For more information, please have a look at this whitepaper: http://www.infomanagementcenter.com/mem ... azquez.pdf


Now I want to create a reference to an indexterm element from a topic. Currently I switch to the text mode and enter manually:

Code: Select all

<task>

  <title>My Task</title>

  <shortdesc/>

  <prolog>

    <metadata>

      <keywords>

        <indexterm conref="../index.ditamap#Index_Foo"/>

      </keywords>

    </metadata>

  </prolog>

  ...

</task>

This is not very comfortable. When I create a conref Attribute, the autocompletion helps me to find the path to the map. But I have to look up the id of the indexterm manually and type "#" followed by the id. It would be nice to completely avoid using the XML plain text mode.

In the author mode I cannot create a content reference to an indexterm element. When I select URL: index.ditamap and Target type: all, the preview list shows nothing. It seems, that it does not work for indexterm elements. But why? Is it possible to add additional target types? So technically generating the index works the way I expect it (pdf2 using DITA-OT2.0, webhelp). Maybe there is another way to create my indexterm references?


Thank you for your feedback

Best regards,
Stefan

[Radu]

Hi Stefan,

I remember that in some recent Oxygen version we decided to inhibit inserting conrefs from topics to maps or from maps to topics because somehow we considered there would be no usecase in doing this.

What you have there is nonetheless a quite unusual way of defining conrefs, for example you could have just as easily created a DITA topic which would have containing reusable indexterm elements inside and refer to that topic in the DITA Maps Manager using the processing-role="resource-only" attribute.

I looked in the specs and the specs says something like:

Code: Select all

When pulling content with the conref mechanism – if the referenced element is the same type as the referencing element, and the list of domains declared on the domains attribute in the referenced topic or map instance is the same as or a subset of the list of domains declared in the referencing document, the element set allowed in the referenced element is guaranteed to be the same as, or a subset of, the element set allowed in the referencing element.

I checked and the @domains attribute of the DITA Map seems to be a superset of the DITA topic @domains attribute. From what the specs says, in order for a conref from a topic to a map to be considered valid, the map domains should be a subset of the topic domains.
Honestly, I do not know if this is a valid way of doing things or not. I'll try to write an email on the DITA TC list and ask for a second opinion on this.

Regards,
Radu

[Radu]

Hi Stefan,

I wrote an email to the dita-comment users list:

https://lists.oasis-open.org/archives/d ... 00000.html

If the received answer is that this is possible, we will change the behavior in Oxygen.

Regards,
Radu

[xephon]

Hi Radu,

thank you very much. I'm curious about the answer.

Best regards,
Stefan

[Radu]

Hi Stefan,

Sometimes the TC is quite late in responding (if they ever do), I think they discuss these issues in their monthly calls in order to find an official answer. You can also register on the OASIS DITA Comment List if you want.
Or you can also ask about this particular situation on the DITA Users List. Maybe somebody from the TC will give his/her opinion on this quicker.

Regards,
Radu

[Radu]

Hi Stefan,

No reply from the TC yet. But I managed to get Eliot Kimber's personal opinion on this in two separate emails:

It's definitely allowed to conref from a map to a topic for those
element
types that are common between topics and maps, so it follows that it
should be possible to conref from a topic to a map.

However, I would consider that bad practice: elements to be conreffed
should be organized into separate topics that contain only reusable
content.

So in this case, I would factor out the index terms into a resource-only
topic and conref them from both the map and content topics.

This is my personal opinion--the TC may feel differently.

I think there are two questions:

1. Is it allowed to conref from a map to a topic or a topic to map under
any circumstances?

2. What are the domain compatibility requirements?

If the answer to (1) is "yes" then normal conref constraints apply (the
fact that it's a topic to a map or map to a topic doesn't matter).

The normal (strict) constraint is that the domains in the referencing
document must be a superset (same as or more than) the domains of the
referenced document.

For DITA 1.3 we are formalizing the notion of "weak" constraints, which
was approved for 1.2 but the new @domains declaration syntax got left out
of the spec.

With weak constraints, processors can choose to allow conref as long as
the base types are the same, irrespective of the domains in play. This
handles the case where a processor will do the right thing and nobody
cares that the resolved, ungeneralized conref result would not be grammar
valid (for example, because the referencing document disallows occurrence
of some base type that is used in the conreffed element).

So right now I would leave that limitation which does not allow making conrefs from topics to maps in-place. But I could remove the other limitation that we have that we do not show referenced elements when making conrefs from maps to topics.

Regards,
Radu

[xephon]

Hi Radu,

very interesting. Thank you very much for your engagement. I subscribed to the list. I thought it is a common practice to organize indexterms on the map, due to the mentioned white paper (http://www.infomanagementcenter.com/mem ... azquez.pdf).

I don't care whether the terms live on a map or in a topic. To clarify: My index.ditamap contains only indexterms and nothing else. I didn't understand, why I should use a map for clustering my terms, as it is mentioned in the white paper. Maybe it was not a good reference.

So I'll follow the recommendation of Eliot. I can bear the effort of refactoring the structure and this makes more sense to me.

Thank you very much Radu!

Best regards,
Stefan

[Radu]

Hi Stefan,

I think that the whitepaper tries the approach of avoiding altogether defining index terms directly in topics. Instead it tries to always define them in the DITA Maps and make conrefs from one DITA Map to another to reuse index terms.
The specs says something like:

http://docs.oasis-open.org/dita/v1.2/os ... #indexterm

An indexterm that occurs in a topic prolog is interpreted as a point reference to the title of the topic. Likewise, an indexterm that occurs in <topicmeta> inside of a <topicref> is interpreted as a point reference to the title of the referenced topic.

So it seems that defining index terms only in topicmeta at DITA Map level on each topicref would be an alternative to adding indexterms in each topic.

Regards,
Radu

[xephon]

Hi Radu,

in our situation it is not necessary to reference indexterm elements from the map. We have multiple maps, but we don't have diverging indexterm elements. So we reference indexterm elements only from topics. I cannot imagine any company/use case, that requires assigning indexterm elements by map, because it leads to duplicate work and is only useful, if you need specific indices.


Best regards
Stefan

[Radu]

Answer from Kris Eberlein (DITA TC):

Radu -- It is perfectly appropriate to conref from a task to topic. Or a title from a map into a topic (or vice versa).

The statement that you quoted from the 1.2 spec -- "When pulling content with the conref mechanism – if the referenced element is the same type as the referencing element, and the list of domains declared on the domains attribute in the referenced topic or map instance is the same as or a subset of the list of domains declared in the referencing document, the element set allowed in the referenced element is guaranteed to be the same as, or a subset of, the element set allowed in the referencing element." -- was not intended to be the whole story.

That is, the content of the sentence is perfectly true -- but it should NOT be read to mean that the domains on the referenced element must be the same or a subset of the domains on the referencing element. If they are the same, super; if not, processors SHOULD generalize.

The sentence that followed this content in the 1.2 spec was " A processor resolving a conref should tolerate specializations of valid elements and should generalize elements in the pulled content fragment as needed for the referencing context."

So apparently anything is possible as long as the class attributes match on the source and target elements
I will remove the current limitations from the dialogs Oxygen uses to insert conrefs.

Regards,
Radu

[xephon]

Thank you, Radu!

[ionela]

Hello,

Just to update the thread, this problem has been resolved in the latest maintenance build of Oxygen 16.1, 2015040615 (released on April 8th):

Author/DITA: "Insert Content Reference" can now be used in a DITA topic to insert a reference from a DITA map and vice versa.

You can download it from our web site:
http://www.oxygenxml.com/download.html

The list of bug-fixes can be found here:
http://www.oxygenxml.com/build_history.html#2015040615

You can follow the release/build RSS feed here:
http://www.oxygenxml.com/rssBuildID.xml

Let us know if you encounter further problems with this new build.

Regards,
Ionela

[xephon]

Excellent, kudos to all of you.

Thanks a lot