Re: Links that are both local and cross-deliverable in shared topics


ekimber@contrext.com
 

Note that in method 1, if you set up the indirect keydefs for the topics that may be in other root maps, authors can blindly refer to the unqualified keys and it's up to map authors to ensure that the referenced keys are bound to either the same-publication use of the topics or other-publication uses, which you can do, for example, by having shared sets of keydefs that "export" the key names for the referenceable topics for each publication so they can be referenced without scope qualification. These keydef maps can easily be generated once you have the pattern set up.

So in your example, for Book A you could generate a map that provides the necessary mapdef to Book A's map and a set of indirection keydefs for use from Book B:

book_a/keydefs/book_a_cross-deliverable-keydefs.ditamap:

<map>
<title>Cross-Deliverable Keydefs for Book A</title>
<topicgroup>
<mapdef keyscope="book_a" scope="peer" href="../book_a.ditamap"/>
<keydef keys="topic_01" keyref="book_a.topic01"/>
...
</topicgroup>
</map>

Then in book_b.ditamap:

<map>
<mapref href="../book_a/keydefs/book_a_cross-deliverable-keydefs.ditamap"/>
...
</map>

The main challenge here is that unqualified keys need to be unique across all your publications, which usually suggests defining key names that reflect the subject of the topic rather than its structural position or source filename, so "install_framitz" rather than "topic_01" so that the keyname is both meaningful to authors and more sensibly unique across all topics regardless of use context.

Then in a topic you can simply have:

<p>Perform task <xref keyref="install_framitz"/> ...</p>

Without having to worry about whether the framitz installation topic is in the same deliverable or a different one.

Note also that it's *map authors* who manage the mapping of key names to uses of topics in the appropriate context.

Map authors have absolute power over key-to-resource bindings (because a root map can override any keydef in any included submap).

This fact suggests that if you've got the kind of re-use and referential sophistication you've described then you need one or more people in a Map Manager job role, responsible for setting key naming policy, key management policy and practice, and construction of the maps themselves, at least as regards key definitions.

Ideally, authors responsible for writing topics (and not for creating maps necessarily) should not have to worry about the key definition details.

Another thing I'll suggest is *put keyscope on everything*, at least on each chapter.

As I've used key scopes more I've come to appreciate how much they help--when you need them you can't do without them and when you don't need them they don't get in the way (or shouldn't).

But for example, by having a keyscope on each chapter, it allows you to easily refer to topics within a chapter from outside clearly and unambiguously. It can also serve to make the subject of a chapter clearer, e.g.:

<bookmap>
...
<chapter keyscope="installation" keys="installation" href="./installation/topic-001.dita">
<topicref keys="prereqs" href="./installation/topic-002.dita"/>
<topicref keys="remove-cover" href="./installation/topic-003.dita"/>
<topicref keys="insert-cart" href="./installation/topic-004.dita"/>
<topicref keys="replace-cover" href="./installation/topic-003.dita"/>
</chapter>
...
</bookmap>

From within the chapter, topics can refer to unqualified keys, i.e., <p>You must satisfy the prerequisites defined in <xref keyref="prereqs"/> ...</p>

And from other chapters you use the key scope: <p>Cover must be removed. See <xref keyref="installation.remove-cover"/>.</p>

Note that all the keys in this example are semantic while the topic filenames are arbitrary and meaningless. This separates the names used to identify and refer to topics in the map and the publication content from the topic storage details. The information nature of the topics will not change but their storage details *will change*.

When you said that my option #2 didn't work--what aspect of it didn't work? The cross-deliverable link is the same in both #1 and #2. The only thing option #2 provides is a way to have a scope-qualified reference work when the target key is in the same root map.

Finally, keep in mind that you can override any scope-qualified key definition by defining a higher-precedence key by defining a key where the key name includes the scope name, i.e.:

<>
<keydef keys="installation.prereqs" href="./topics/installation/prereq-for-ios15.dita" platform="iOS15"/>
...
<chapter keyscope="installation" ...>

Cheers,

E.
--
Eliot Kimber
http://contrext.com


´╗┐On 6/9/21, 6:32 PM, "Chris Papademetrious" <main@dita-users.groups.io on behalf of chrispitude@gmail.com> wrote:

Thanks Eliot! Excellent summary of the problem and the situation.

Your method #2 (adding a map-level @keyscope) is what I tried, but it doesn't seem to work in Oxygen. It doesn't form the cross-book links properly, and if I create them by hand, they don't resolve.

I will try method #1 tomorrow. However, I'm not sure how well it would work in practice, as the writers want to share entire chapters between books, with a variety of cross-references to both book within the chapters. Trying to create all the local/cross-book flavors of indirection links would be quite maddening!

The good news is, your reply and suggestion for method #2 gives me the confidence that this should be fixable in Oxygen. Thank you so much!

- Chris

Join main@dita-users.groups.io to automatically receive all group messages.