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


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.

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

<map>
ÂÂÂ <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>
</map>

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.

Jim

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.)

Cheers,

E.

--
Eliot Kimber
http://contrext.com
ï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?

     Jim


     ---------------------------------------------------------------------
     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:
     https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php





---------------------------------------------------------------------
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:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php



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