Need Clarification of The Meaning of scope="peer"

[Eliot Kimber <ekimber@reallysi.com>]

The current 1.2 lang spec draft (3/24/09) says this for the value "peer" of
@scope:

"Set scope to peer when the resource is part of the current set of content
but is not accessible at build time. An implementation may choose to open
such resources in the same browser window to distinguish them from those
with scope set to external."

I think there are several problems with this definition that need to be
addressed in the 1.2 spec (see issues below), but since addressing those
problems could potentially imply new or different processing requirements or
language semantics, I want to see if there is consensus about what peer does
or should mean before I start suggesting new language.

Background: my understanding of peer has always been "same data set but
different unit of publication", where by "data set" I mean "set of DITA
topics and maps managed together as a coherent set of interrelated data
objects", e.g., all the topics created for a library or an enterprise or
whatever, with the implication being that dependencies among topics maps
within the set are knowable and manageable by a single agency (e.g., a
single CMS, a single set of coordinated authors using common business and
editorial practices, etc.).

I developed and use this understanding primarily as a way to make
cross-publication dependencies sensible using DITA-defined mechanisms, in
particular, @scope on topicrefs and xrefs.

In order to be able to sensibly author publication-to-publication references
there needs to be a reasonably-clear understanding in DITA about what the
boundaries of publications as authored and as published are. I have always
used the definition of "root map+scope-local dependencies" for "publication"
in a DITA context, meaning that given some top-level map, its direct
components as published consist of only those resources that are directly or
indirectly referenced as local-scope dependencies. Any dependencies with
scope=peer or scope=external are, by [my] definition, in other publications,
as represented by their own top-level maps.

[Note that, with the possible exception of bookmap, DITA has no standard way
to distinguish maps that represent top-level units of publishing from maps
that represent either aggregations of publications or sub-publication
components ("submaps"). I don't think we need to solve that problem for 1.2
(even if we could at this late date), I just make the observation that
without such a standard mechanism, all semantics related to managing DITA
content as publications is necessarily implementation dependent and
therefore likely to be non-interoperable.]

However, the definition of peer as quoted above does not, necessarily,
support that understanding.[End Background]

--------
Issue 1: 

The phrase "the current set of content" is not well defined: the term
"current" has no obvious defined context by which to be bound to some
definable concrete thing.

Does it mean "all the topics and maps to which I have immediate access and
access rights"?

Does it mean "all the topics and maps referenced, directly or indirectly,
from the root map being processed?

Does it mean "whatever I say it means"?

I realize that any definition of "current set of content" will be
necessarily fuzzy but I think we can make it a bit more concrete, or at
least define a default implication relative to common use cases
(filesystems, CMS systems, etc.).

--------
Issue 2: 

It's not clear, at least from the above, whether there is an expectation
that a given publication could directly include as part of its
directly-published content (e.g., within its PDF or CHM package) resources
with a scope of "peer". My initial take would be "no" but I can imagine
others might have exactly the opposite expectation.

--------
Issue 3:

The statement "An implementation may choose to open such resources in the
same browser window to distinguish them from those with scope set to
external." is clearly in reference to a specific rendition type and does not
help clarify the abstract semantic of peer (part of current publication or
not part of current publication).

This text, if retained, should at least be put in a non-normative note as an
implementation suggestion.

-------------------
Consensus Question:

Is there anyone out there who does *not* take peer to mean "known but in a
different publication"?

If so, what do you take peer to mean and how do you apply that meaning in
practice?

Cheers,

Eliot

----
Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>
office: 610.631.6770 | cell: 512.554.9368
2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com
<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>