[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Direct Links In a CCMS environment
Comments below:
On Tue, Nov 17, 2020 at 6:48 AM Kristen James Eberlein
<kris@eberleinconsulting.com> wrote:
>
> 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?
Cross book links without keys is interesting because there could be
1000 topics in any other book and naming and maintaining the keys for
each topic is an extra maintenance task.
>
> 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.
The extra idea for resourceId is to add a keyref to it to allow a user
to identify a re-used topicref.
>
> Best,
> Kris
>
> Kristen James Eberlein
> Chair, OASIS DITA Technical Committee
> OASIS Distinguished Contributor
> Principal consultant, Eberlein Consulting LLC
> www.eberleinconsulting.com
> +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.
> >
> > <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
> >>
> >
> > ---------------------------------------------------------------------
> > 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]