OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] Direct Links In a CCMS environment

Jim, I'm confused.

I think you are suggesting an alternative mechanism for cross-deliverable linking that does NOT use keys. Why would we want to consider this?

Also, it's past time for us to consider any new additions to DITA 2.0.

I do not see this as something appropriate to add to the proposal concerning removing @copy-to.


Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
+1 919 622-1501; kriseberlein (skype)

On 11/15/2020 1:45 PM, Jim Tivy wrote:
Hi Folks

Thanks for the discussion Nov 10th.

I come away with three ideas: first one regarding cross publication links and the following ones regarding topic "use" links.

1. A pubId as part of an address for cross publication linking is useful and could be part of DITA or just a CCMS mechanism. That using a pubId on a cross publication link would be acceptable with the understanding that some pubId to rootMapUri lookup hosted by the environment would resolve the pubId to a publication rootmap. This would provide a cross deliverable direct linking strategy for CCMSes and other systems that may have all the publications available. Such a direct cross publication link might look like <xref href="./oil.xml#a23445/dipstick" pubId="Maintenance" />

Going Forward: Either persue in DITA or persue as CCMS extension to DITA.

2. Direct addressing of a topic "use" is limited without an idScope
Direct addressing of a topic "use" is limited. The useId in such an address could refer to the topicref id attribute. However, in the case where the "same" topicref is used in two use contexts you need scoping to select the use tree branch.

For example in the Main Map below there are effectively two "uses" of <topicref keys="m" href="moo.xml"/>. One use in scope X and one use in scope Y.

ÂÂÂ <title>A Map</title>
ÂÂÂ <topicref id="m_guid" keys="m" href="moo.xml"/>

ÂÂÂ <title>Main Map</title>
ÂÂÂ <topicref keyscope="X" href="a.ditamap" format="ditamap"><ditavalref href="novice.ditaval"/></topicref> ÂÂÂ <topicref keyscope="Y" href="a.ditamap" format="ditamap"><ditavalref href="expert.ditaval"/></topicref>

To indirectly address use Y would require using <xref keyref="Y.m" />. This would seem to be in keeping with the proposal on removal of copyto.

As a side note, to directly address the Y use using the topicref id="m_guid" would require an idScope that behaves like keyscope. Adding such a parallel concept may not be pragmatic.

Another side note, is key referencing can only choose one branch but if somehow there were branches within branches of same topicrefs you would need multiple keyscopes in the address. eg: keyref="Y.Q.m"

Going Forward: Use keys and keyscopes for designating use where use is ambiguous. Consider useId attribute on links for a direct use linking method going forward.

3. Specification of a resourceId is limited without the use of keys
Specifying a resourceId for an appname such as:
ÂÂÂ <topicref keys="m" href="moo.dita">
ÂÂÂÂÂÂÂ <topicmeta>
ÂÂÂÂÂÂÂÂÂÂÂ <resourceid appid="aboutMoo" appname="csh"/>
ÂÂÂÂÂÂÂ </topicmeta>
ÂÂÂ </topicref>

Is limited as it does not allow the designation of a topic "use" in the "same referenced topicref" case explored in #2 above.
To remedy this <resourceid could use a keyref
<resourceid keyref="cshmoo" />

where the cshmoo key is defined for each branch X and Y. The details of how to define these keys would be have to be worked out.

Going Forward: As part of copyto proposal 33 look at supporting keyref and work out key definition mechanism.


On 11/10/2020 6:24 AM, Eliot Kimber wrote:
Linking in the face of reuse requires some form of indirection. In DITA this is keys.

So you can either use keys or you can use the proprietary equivalent.

There is no other way to do it.

That is, there is no mechanism that would be A) functionally equivalent to keys and B) simpler than keys.

Doing address management in versioned hyperdocuments that include the possibility or fact of re-use is inherently difficult and cannot be solved without some form of indirection.

Keys is the indirection mechanism in DITA.

Docbook has "OLinks", which are a weaker form of indirection, but it requires the use of implementation-specific "olink databases".

The DocBook mechanism is workable only because (historically) DocBook did not do re-use, so there was a one-to-one relationship between DocBook documents (and more importantly, elements within those documents) and the deliverables to which they could be published.

This is big simplifying assumption and allows having a single, simple database that maps source elements to deliverable targets. (And remember that XInclude is *not* re-use, it's copy-and-paste because it is functionally equivalent to external parsed entities because the elements referenced via XInclude are parsed as though they were were part of the referencing document. XInclude does provide for ID rewriting when the IDs of included elements would conflict with the IDs of other elements in the same XML document, but that only fixes a design flaw in SGML (inherited by XML), it does not enable true use-by-reference of content in the way that DITA does.)



Eliot Kimber

ïOn 11/9/20, 9:08 PM, "Jim Tivy" <dita@lists.oasis-open.org on behalf of jimt@bluestream.com> wrote:

ÂÂÂÂ Hi Folks

ÂÂÂÂ xrefs are often used to link from one DITA source topic to another - ÂÂÂÂ perhaps not always best practice but used nonetheless. In a CCMS an xref
ÂÂÂÂ can either be to the same publication (same pub link) or to another
 publication link (cross pub link). A CCMS will typically host all the
ÂÂÂÂ publications of a particular project.

 As well, xrefs can be a link to any number of "uses" of a topic within a  publication. A "use" refers to a single topicref to a given topic in
ÂÂÂÂ the expanded map of a publication.

ÂÂÂÂ So in a CCMS, a full direct address to a topic would be composed of
ÂÂÂÂ {publicationId}{topicUri}{useId}#{topicXmlId}/{elementId}. Certainly
ÂÂÂÂ {publicationId} and {useId} could be dropped for simpler same pub
 cases. But for the full on cross pub and use location cases, all 5
ÂÂÂÂ parts are needed.

ÂÂÂÂ Unfortunately right now in DITA you can only directly address
ÂÂÂÂ {topicUri}/#{topicXmlId}/{elementId}.

ÂÂÂÂ We have numerous customers that wish to have direct cross publication
ÂÂÂÂ linking at a source level without the need for keys. Once you have
 addressing at the source level the user can move around freely through  the source in the CCMS. As well, the CCMS can enforce link integrity  across publication. As well, at publish time these source links can be  converted too other link forms that work in target delivery platforms
ÂÂÂÂ removing the need for subsequent explicit <resourceId> entries.

ÂÂÂÂ So far I am not aware of a simple DITA way of doing cross publication
 links aside from the key proposal. As well, our discussion of
ÂÂÂÂ <resourceid> has focused on external identity but not source identity.
ÂÂÂÂ Is this a shortcoming or am I missing something?


ÂÂÂÂ To unsubscribe from this mail list, you must leave the OASIS TC that
 generates this mail. Follow this link to all your TCs in OASIS at:

To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:

To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at:


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]