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: Nancy <nancylph@gmail.com>
- Date: Wed, 25 Jan 2012 14:20:07 -0500
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="">
>
> (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]