10.1.1 Referencing internal and external maps and topics

Processing requirements limit what DITA2Go can do to support copying content from and to internal and external maps and topics. Table 10-1 summarizes the restrictions.

Table 10-1 DITA2Go support for push and pull conrefs

Conref from:

to:

Internal target

External target

Restrictions

Push

Pull

Push

Pull

map

map

No

No

No

Yes

Pull only, from external map only

map

topic

Yes

No

No

Yes

No internal pull; pushreplace only

topic

map

No

Yes

No

Yes

No push from topic to map

topic

topic

Yes

Yes

No

Yes

All five push variants

Nothing external to your project can be processed, except to pull from as a source. In other words, DITA2Go does not handle any of the following:

Conref from map to map

Map-to-map conrefs can be pull only (no push), and only from a map external to the project. You can use map-to-map pull topicrefs to pull in topicrefs from another map, to provide a form of indirection that does not employ keyrefs, which are not included in DITA version 1.1. You can swap in different maps containing topicrefs with the same IDs but different attributes; and the main map will add topicrefs from the other maps at run time.

For example, if you have product-specific information to be included in many different places, you can have a topicref with a conref at each such place. However, you cannot use the same topic in the same map in two places, unless you use branches to distinguish them; see §9.6 Scoping and filtering within maps.

Note:  Map to map conkeyrefs are not supported, because it is not possible to resolve keyrefs until maps are totally resolved, which cannot be done if any conkeyref is present that can add a map; see §10.1.3 Understanding problems with processing conkeyrefs.

Conref from map to topic

A map cannot pull from a topic. By the time the topic is processed it is too late to affect map processing in any useful way, even from external topics. Map processing has to be finished (to resolve keyrefs) before any conrefs, and after that, changing the original elements cannot affect the already processed results. Only an internal map can push, and only pushreplace, not pushafter or pushbefore.

Conref from topic to map

The topic with the conref must be internal to the project, and can pull from either an internal or an external map. However, a topic cannot push to a map, because map processing is finished before topic processing begins.

Conref from topic to topic

Push and pull are supported between internal topics. Pull is also supported from external topics, but you cannot push to an external topic. Push includes all five variants, two of which (pushatstart and pushatend) are extensions not present in the DITA 1.2 specification; see §10.1.2 Pushing content into an element.

Previous Topic:  10.1 Pushing and pulling content by reference

Next Topic:  10.1.2 Pushing content into an element

Parent Topic:  10.1 Pushing and pulling content by reference

Sibling Topics:

10.1.2 Pushing content into an element

10.1.3 Understanding problems with processing conkeyrefs

Table of ContentsIndex