dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [dita] Proposal 13041 and Cross-Publication Linking
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: "Nitchie, Chris" <cnitchie@ptc.com>
- Date: Wed, 25 Jan 2012 14:48:48 -0500
From your proposal:
The DITA 1.2 specification dictates that there be exactly
one effective definition for a given key for all key references within
a map structure (see “Effective key definitions” here).
This is a severe limitation that prohibits some common use-cases, such
as:
| •
| Omnibus publications that combine multiple standalone
maps, each with their own set of key definitions. |
| •
| Cases where a topic is reused at multiple locations in
a map structure, but the behavior of links and/or text replacement for
each use context must be different. |
The omnibus publication case is the
flipside of the cross-deliverable referencing. The same keyref must be
resolvable as cross-deliverable in the separated case, or same-deliverable
in the omnibus case.
From my message here: http://lists.oasis-open.org/archives/dita/201109/msg00028.html
A.ditamap
<topicref keys="a1" href=""
<mapref processing-role="resource-only"
href="" <!--gets
keys to allow a1.dita to reference b1.dita via keyref-->
B.ditamap
<topicref keys="b1" href=""
A1.dita
Hey here's a cross ref: <xref keyref="b1"/>
<!--resolves to b1.dita at authoring time-->
If we now add a requirement for scoping
to this picture - that is, B.ditamap potentially has keys in conflict with
A.ditamap keys - how can A1.dita's xref be adjusted in a way that it still
builds normally in both the omnibus case and the separate deliverable case?
Michael Priestley, Senior Technical
Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
From:
"Nitchie, Chris"
<cnitchie@ptc.com>
To:
Michael Priestley/Toronto/IBM@IBMCA,
"Nancy" <nancylph@gmail.com>,
Cc:
"Helfinstine,
David" <dhelfinstine@ptc.com>, "dita" <dita@lists.oasis-open.org>,
"Eliot Kimber" <ekimber@reallysi.com>
Date:
01/25/2012 02:33 PM
Subject:
RE: [dita] Proposal
13041 and Cross-Publication Linking
They’re not connected because
they’re two completely different use cases.
1. Refer
to a location in another publication via the map and key name from which
the publication was generated, the resolution of which is processor-dependent.
2. Have
different key resolution behavior at different locations in a single map
structure, the resolution of which is strictly controlled by the spec.
Chris
From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Wednesday, January 25, 2012 2:20 PM
To: Nancy
Cc: Nitchie, Chris; Helfinstine, David; dita; Eliot Kimber
Subject: Re: [dita] Proposal 13041 and Cross-Publication Linking
Hi all,
My question is, why aren't the two more connected than they are?
If we can use map containment to distinguish between keys that we need
to address, why can't we use map containment for scoping keys as well?
Or if we need a different scoping mechanism so that we can allow information
architects to alternate between first-definition-wins and local-definition-wins
in the keyref wars, then why can't that same scoping mechanism be used
for cross-scope references?
If we need to be aware of both map containment and scope containment, that's
two roughly equivalent trees of containment that will need to be preserved
throughout any processing pipeline - can't we just make do with one?
I'm also assuming that either way we did it, the author would not need
to code complex nested URIs - either way, they should be able to code simple
two-part keyrefs:
For example, if we have either a nested scope or nested map structure -
a map/scope contains b map/scope contains key x
then x should be addressable in any of the
following ways:
keyref="b/x" finds the definition
of x within b
keyref="a/x" finds the first definition
of x within a
keyref="x" if the reference is from
within b, finds the first definition of x within b; otherwise if the reference
is from within a, finds the first definition of x from within a; otherwise
finds the first definition of x in the whole keyspace (ie behaves normally)
Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
From: Nancy
<nancylph@gmail.com>
To: Eliot Kimber
<ekimber@reallysi.com>,
Cc: "Nitchie,
Chris" <cnitchie@ptc.com>,
Michael Priestley/Toronto/IBM@IBMCA, "Helfinstine, David" <dhelfinstine@ptc.com>,
dita <dita@lists.oasis-open.org>
Date: 01/25/2012
01:40 PM
Subject: Re:
[dita] Proposal 13041 and Cross-Publication Linking
Chris,
Thank you for the extremely clear explication of cross-scope key referencing,
and Eliot, thank you for your succinct explanation of your and Michael's
difference of opinion on it.
It appears to me that the only real connection/dependency between cross-scope
keys and key scoping may be in the attribute name being used. End
users may - almost certainly will - be confused by attributes with such
similar names, especially when both can be used in relation to keys.
After all, I was, and I'm not a new end-user.
@scope already exists, and @keyscope is certainly descriptive, but we'll
have to include this in our 'users need lots of support if we don't what
them to throw up their hands and pick another technology' bucket, as part
of our 1.3 work on reducing DITA barriers to entry.
Regards,
Nancy
On Wed, Jan 25, 2012 at 10:04 AM, Eliot Kimber <ekimber@reallysi.com>
wrote:
Chris,
I need to take more time to read your analysis more carefully, but I believe
that you have correctly divined my intent: the ability to address by key
something in another "publication" as authored, as represented
by its root
map.
As you say, how a given processor makes that work in rendered results is
necessarily processor specific.
Where Michael and I were arriving at in our discussion was that one could
define a purely key-based way of representing the processed result by
creating intermediate key sets that point not at the content as authored
but
at the content as rendered. Whether these keys are generated or authored
or
manipulated by hand in the middle of some production process is
immaterial--the point is that such keys can fully represent the relationship
between a given key reference and any particular rendered version of the
target resource. Thus they can serve as both a standard language for talking
about those relationships in an abstract processing context and can serve
as
a literal interchange format so that two otherwise distinct processors
could
collaborate on output production.
The only place where I think Michael and I differ is on the need for the
specific key-based fragment identifier syntax. I feel strongly that we
need
it and I'm pleased that you seem to be arriving at the same conclusion.
Cheers,
E.
On 1/24/12 6:54 PM, "Nitchie, Chris" <cnitchie@ptc.com>
wrote:
> Eliot, Michael,
>
> In preparation for tomorrow's telcon, I spent some time going back
over the
> cross-scope key reference discussions from August and September, thinking
> about how 13041 interacts with key scoping, and writing up a thorough
> description of why I thought cross-publication key referencing was
a really
> bad idea. Somewhere during that process, though... I think I changed
my mind.
> Eliot, tell me if I'm on the same page. Michael, let me know if this
makes any
> sense. And I apologize if some of this is a bit pedantic; this was
just my
> thought process.
>
> Here's the quote from Eliot that clued me in to what he's going for
(emphasis
> in the original)
> (http://lists.oasis-open.org/archives/dita/201109/msg00029.html):
>
> <quote>
> The author *of a topic* references some target by key. At the time
they
> author the reference to the key they can't know or care where the
ultimate
> target of the key might be in the content as authored or in the content
as
> rendered, for the simple reason that it is unknowable at authoring
time.
>
> If they are authoring in the context of a specific map then of course
they
> can know where the key resolves in the context of that map, but if
they are
> authoring the topic outside of a map context then they are simply
stating
> the requirement that there needs to be something at the end of the
key in
> whatever contexts that topic is used. But they cannot know all the
possible
> maps the topic might be used by in the future.
>
> The author *of a map* that uses the topic has the responsibility of
binding
> the key to a resource. If the resource is in the same map, then no
problem,
> they just create a normal key reference and they're done.
>
> But if the resource is *not* in the same map, *there is nothing they
can do
> today to indicate their intent to reference a resource in a different
map*.
> </quote>
>
> Ignore keys and key scopes and key spaces and all that stuff for a
second.
> What's the correct way to code a reference to a specific location
in a map
> that represents a separate publication? DITA 1.2 doesn't say, but
I think it's
> this:
>
> @format="ditamap"
> @scope="peer"
> @href="" uri)#(branch ID)"
>
> The current topic discussing the scope attribute in the 1.2 spec is
both hard
> to understand ("Set scope to peer when the resource is part of
the current set
> of content but is not accessible at build time") and a little
bit weird ("An
> implementation may choose to open such resources in the same browser
window to
> distinguish them from those with scope set to external"). But
I think this
> formulation is reasonable. If not, maybe we need a new value for @scope,
> something like "sibling."
>
> The big problem with cross-publication linking in any XML content
system, not
> just DITA, is that the process of mapping an XML resource to its published
URL
> depends on more variables than can be accounted for in a generic,
> one-size-fits-all way. Once the spec describes the appropriate way
to encode a
> cross-publication reference (and again, I suggest the above), it must
> necessarily throw up its hands and say, "the processor does whatever
it can to
> resolve this reference according to business rules and composition
parameters
> and whatever other data it can get its hands on. Processors may not
be able to
> resolve such references in all situations, and processing such references
is
> not a requirement for conformance." You guys (Michael and Eliot)
spent a lot
> of time last fall speculating about how hypothetical processors might
solve
> the problem, but just for illustrative purposes, and not, I think,
as
> proposals for the spec. I don't believe there's any way for the spec
to
> prescribe a solution to this problem.
>
> So let's take a key, "maintenance.intro". In one map, the
maintenance manual
> is part of the publication, so the key definition is simple:
>
> <keydef keys="maintenance.intro" href="">
>
> In another map, the maintenance manual is its own publication. With
any luck,
> the maintenance manual map has an ID on the topicref to intro.dita,
so in
> those contexts you'd define the key like so:
>
> <keydef keys="maintenance.intro" scope="peer"
> format="ditamap" href="">
>
> This is sufficient information for any processor to try and resolve
the
> reference. "I want to point to the 'intro' topic of the publication
derived
> from maintenance.ditamap that applies for my current publishing context,
> however that's defined."
>
> I think proposal 13041 essentially comes down to this: Given that
the
> processing of peer references must be processor-dependent, you should
be able
> to specify a key name for the above reference instead of a branch
ID.
>
> <keydef keys="maintenance.intro" scope="peer"
> format="ditamap" href="">maintenance.ditamap#@intro"/>
>
> (Note: I don't care what the URI structure ultimately is, the point
is, it's a
> key, not an ID.)
>
> The author's intent is clear. "Point to whatever content fulfills
the role of
> 'intro' in the publication derived from 'maintance.ditamap' that applies
for
> my current publishing context, however that's defined." The resolution
is left
> up to the implementation. And topic authors are shielded from having
to know
> anything about key scopes and usage contexts and all that stuff.
>
> I'd prefer that we specify that processors should issue an error if
the '@'
> syntax (or whatever) is used anywhere but on a peer-scoped references,
and
> maybe even if it's used on anything but a resource-only key definition,
as
> only map authors can know whether or not a given map is part of the
same
> publication.
>
> If my interpretation of the proposal is correct, count me as on board.
>
> None of this, so far as I can tell, has anything to do with key scoping.
>
>
> Chris Nitchie
> Senior Software Engineer
>
> T 734.352.2879
F 734.997.0201
> E cnitchie@ptc.com
>
> PTC.com
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: dita-help@lists.oasis-open.org
>
--
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: dita-help@lists.oasis-open.org
--
_____________
Nancy Harrison
Infobridge Solutions
nharrison@infobridge-solutions.com
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]