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: Proposal 13041: Addressing keys in other key spaces


Per the discussion on the phone, my requirement is to be able to point to a
different root map in order to address keys in that key space as a separate
key space. This is a different requirement from that addressed by Proposal
13004, which is about scoping keys within a single map tree.

My original thinking was that being able to bind a key reference to any map
would also address the within-map-tree scoping requirements addressed by
13004, that is, if I can address a map as a distinct key space, it doesn't
matter whether it's inside or outside the currently-processed map tree.

However, the minimum requirement is for cross-publication addressing, which
means addressing a root map (representing a separate key space) and then a
key within that key space so that the data as authored unambiguously
represents a key-based relation between something in one publication (root
map) and something in another publication (different root map).

I had been thinking of perhaps a new attribute for use with @keyref but
based on the discussion I think it might be sufficient to define a fragment
ID syntax that means a reference to a key within a root map's key space.

Given that it would then be possible for references to maps with a scope of
peer or external to unambiguously mean a reference to a key in a different
key space. The @type value would reflect the expected type of the referenced
resource, e.g., "dita" for topics.

We could further stipulate that the only allowed type is "dita" since it
wouldn't really make sense to link to peer or external-scope non-DITA
resources--what would that mean in terms of document-to-document links in a
rendition? I don't think it would make any sense. In the context of a
*rendered* DITA publication, the only thing you can meaningfully address are
elements.

For example consider this key definition in the key space defined by map
Doc-A.ditamap:

<keydef keys="doc-B-chapter-01"
  scope="peer"
  format="dita"
  href="../Doc-B/Doc-B.ditamap#keyname:chap-01"
/>

This keydef is doing the following:

1. Defines the key "doc-B-chapter-01"

2. Indicates that the referenced resource is a peer (that is, not part of
the publication represented by Doc-A.ditamap).

3. Indicates that the expected format of the ultimate target is a topic (and
not a DITA map).

4. Via the HREF, addresses the key defined in the keyspace rooted at map
Doc-B.ditamap.

That information is sufficient for a processor to do whatever it needs to do
to generate the appropriate rendition-specific artifact that implements the
link from something in Doc-A to the thing bound to key "chap-01" in the
scope of Doc-B's key space.

Because the URL reference is to a DITA map, it means there's a natural
fallback when the processor can't generate a direct element-to-element link,
namely a link to the rendition of the map as a whole, which is the best you
can do today with DITA-defined addressing semantics. For example, a PDF
generation process could generate the result link to the URL "../Doc-B.pdf"
and be as reliably correct as the current Toolkit HTML process is when it
changes "foo.dita" to "foo.html" when generating HTML output. Or, if you
know that all PDFs will be served from some common root URL, you could
specify that as a run-time parameter. Or whatever.

The new bit of syntax for the URL reference is the fragment identifier. Here
I've added "keyname:" as a signal that the fragment identifier is a
reference to a key name and not to an ID of an element within the map. That
syntax isn't idea because a key name could itself include a ":" but it gets
the idea across. Would have to think more deeply about the syntax details.

The only alternative approach I can think of would be to use a query rather
than a fragment identifier, e.g.:

href="../doc-B/doc-B.ditamap?keyref=chap-01"

However, we tend to think of queries as being processor-specific and have so
far not specified any standard query parameters or semantics (that is, we
haven't defined a DITA access API). So I'm not as keen on using URL queries.

Thinking it through here I'm satisfied that this approach would satisfy my
requirement for key-based cross-publication element-to-element linking.

It leaves open the question of whether we should allow this form of
URL-based key reference to point to local-scope maps, that is, something
like:

<keydef keys="thing-01-in-chapter-2"
  scope="local"
  format="ditamap"
  href="chapters/chap-02/chap-02.ditamap#keyname:thing-01"
/>

I think this makes sense mechanically but it might be too much overlap with
Chris' key scoping proposal.

Cheers,

Eliot 

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com



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