Re: [dita] RE: [Dita-ot-developer] Handling of xref attributes

[Michael Priestley <mpriestl@ca.ibm.com>]

Re the scope attribute: the current
definition is this:

The scope attribute identifies the closeness
of the relationship between the current document and the target resource.

- Set scope to local when the resource
is part of the current set of content, and should be accessed and copied
to the output directory. 
- Set scope to peer when the resource
is part of the current set of content but is not accessible at build time.

- Set scope to external when the resource
is not part of the current information set and should open in a new browser
window. 
The default is local.

Re:
>Having components authored by other people is
the norm in topic oriented
>authoring. If it is part of your "information set" then the
momentary
>unavailability of the information strikes me as a transient problem
that
>should be reported as a warning. If I shut up the warning by setting
the
>scope attribute to "peer" then I'll never fix my problem
before
>publishing.

If it's a transient problem you wouldn't set scope="peer"
you'd set scope="local". But if it's an ongoing situation (like,
for example, you are publishing a component of a website, and someone else
from another company is publishing another component) then while you are
part of different publishing streams you are converging on the same deliverable,
and want the output to act integrated even though some of the info has
to be "faked" at build time. That's when you set scope="peer".

I hope that clarifies. 

Michael Priestley
IBM DITA Architect
Classification Schema PDT Lead
mpriestl@ca.ibm.com

"Paul Prescod" <paul.prescod@blastradius.com>

02/09/2006 07:02 PM

To	"Robert D Anderson" <robander@us.ibm.com>
cc	<dita@lists.oasis-open.org>, <dita-ot-developer@lists.sourceforge.net>, "Su-Laine Yeo" <su-laine.yeo@blastradius.com>
Subject	[dita] RE: [Dita-ot-developer] Handling of xref attributes

> > What should a DITA processing application
do with the "scope" and 
> > "format" attributes? What does the Toolkit do?
>
> The toolkit treats scope="local" as a local file, available
> for builds. It considers scope="peer" as part of your 
> information set, but something that is not necessarily 
> available to you at the moment (such as another component for 
> your product, which may be authored by somebody else).
> Scope="external" is anything outside of your information
set.

Having components authored by other people is the norm in topic oriented
authoring. If it is part of your "information set" then the momentary
unavailability of the information strikes me as a transient problem that
should be reported as a warning. If I shut up the warning by setting the
scope attribute to "peer" then I'll never fix my problem before
publishing.

Let me propose definitions for the three values that make sense to me,
in case my intuition happens to be right:

 * local means: internal to this map (e.g. within the help file or PDF)
-- the toolkit should fix up the links itself.

 * peer means: across deliverables (e.g. one PDF on a CDROM/website to
another, one set of HTML files to another) -- the toolkit MUST ask some
third-party multi-deliverable-capable link management application how to
fix up the links

 * external means: an address that should not be managed at all. Just
pass it through as a URL.

Does that makes sense? How does IBM handle links between deliverables
(e.g. when deliverables are merged at install time or deliverables refer
to each other on external websites).

> ... I'd be happier if 
> we could point users to a list of common values.

Arguably a mailto is not a "format" but the others could be represented
by MIME types. There is a long-standing debate in the markup world about
whether it is really a good idea to hard-code the type of a target at
the source. At that point the type is doubly identified: in the "format"
attribute and in the metadata associated with the target in the CMS or
on the web server (perhaps driven by the file extension). Representing
the same information twice provides opportunities for inconsistsency.
For example if you link to something that is a PDF today but an HTML
tomorrow, then your format attribute is misleading. I'm not much of a
purist on this point.

 Paul Prescod