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


ekimber@contrext.com
 

Cross-deliverable links are a challenge for a number of reasons, but chief among them is the potential configuration complexity inherent in the fact that a single set of root maps can produce many different deliverables of different types and with different configurations. If there's an exact one-to-one mapping from source root maps to deliverables the problem is easy, but as soon as you can have two or more deliverables from a single root map, the problem gets much more challenging.

The DITA *source* markup makes it possible to unambiguously create a reference to any element in any topic in the context of a specific root map. This is necessary but not sufficient.

When you produce a given a deliverable from a root map you have to be able to control how the source-to-source links translate to deliverable-to-deliverable links when there are multiple possible deliverables for a given target root map.

That's exactly the scenario you described with the use of filtering applied to root maps to produce multiple deliverables from a single root map reflecting different filtering conditions.

Thus there has to be some way to configure the deliverable production process so that sets of related deliverables are produced correctly, i.e., for a set of inter-linked root maps, some way to ensure that the same filtering conditions (or the *correct* set of filtering conditions) is applied to a set of deliverable production processes so that the resulting deliverables are correctly linked to each other. This requires some sort of deliverable production project manager that gives you a way to configure the deliverable generation details.

For example, if you need to produce a set of interlinked deliverables that all reflect macOS, you need a way to specify not just the filtering but the deliverable URIs *as published* to that the links will be to the right place.

Using different wrapper maps that have different ditaval refs and result in different deliverable names is one way to do that and might be the easiest but it seems like that could quickly get either unwieldy or confusing or just impractical.

DITA OT's new project facility seems like at least a start for this kind of production processing configuration manager but more is probably required to fully coordinate the production of multiple interlinked deliverables that have different input parameters (different filtering conditions, etc.) and different result details (different publishing locations for the deliverables).

It sounds like you're able to impose simplifying assumptions that make the problem easier to solve in your environment, which is good--keeping it as simple as you can and still meeting requirements is always a good idea.

A challenge for a tool like DITA OT is that a more general solution starts to become pretty complex pretty quickly, which makes it less likely anyone will take a stab at implementing it...

Cheers,

E.

--
Eliot Kimber
http://contrext.com


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

Hi Eliot,

The bug with Oxygen is when option #2 is used ((1) the current book A has its own local scope A, and (2) it references a peer book B with scope B, and (3) you drag-and-drop a topic from map B into a topic in map A to create a cross-book link), the link is incorrectly created as "B.B.topic1" instead of "B.topic1". SyncroSoft has confirmed it's a bug.

It would be hard to separate writers from their maps here. Each technical writer is assigned 1-3 products, and they own the user guides and reference manuals for those products. Because the map controls both PDF and OLH content delivery, the writers work with maps as tightly as they do the topics.

So, I try to empower the writers to manage their own maps by


* Keeping map structures and rules as simple as possible
* Using Schematron rules to keep writers on the right path
* Relying on Oxygen to make things like cross-book link creation easy

So far, this combination has allowed us to be successful without the need for map/key managers and such, and without the writers having to get too much into the technical DITA stuff. For the most part, it's just writing and Oxygen GUI stuff. And I'll ride that for as long as I can! (And quite frankly, we're not resourced for anything more.)

We're already using peer-book scopes, so local scopes should be a straightforward conceptual extension for the writers to learn. Once this double-scoping bug is fixed in Oxygen, we should be in good shape for creating cross-book links in topics reused across books, which is really cool.

The next hurdle is creating cross-book links between books that use profiling conditions to publish one map to multiple deliverables. Writers want the ability to cross-link to specific conditional versions of books, and also to cross-link automatically between same-condition books. I've had some success prototyping this with a "wrapper map," which is a simple <map> that has only a <ditavalref> and a <mapref> to a full <bookmap>. I plan to share more about that here when the loose ends are ironed out.

The tip about books being able to provide overriding key definitions is a good one - thank you!

- Chris

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