Re: [dita] How much flexibility do specializers have to make exceptionsto behaviors that are outlined in the DITA standard?

[Eliot Kimber <ekimber@reallysi.com>]

Ogden, Jeff wrote:
> JO: Allowing a reference of the form “#elementid” to reference sub-topic 
> content.
> MP: if someone's using a CMS and assigning GUIDs to every element, they 
> may actually have one unique identifier per element, rather than per 
> topic+element.


> JO: Using a single GUID to reference DITA sub-topic content should not 
> be allowed. No exceptions.

> MP: That said, I see your point - it would be preferable for the tool to 
> externalize the reference as properly formed DITA, even if it is 
> internally managed differently. I can easily see the syntax of the href 
> and conref attributes, along with the domains and class attributes, as 
> being immutable. That said, if someone wants to override what they do 
> with that syntax (for example, fetching the linktext for the subelement 
> from its parent topic), I would think that's reasonable.

I agree that all the addressing has to be as it is defined in the DITA 
spec, which explicitly disallows this case.

Note that MP says "override what they do with that syntax"--but it's not 
the *syntax* they're overriding, it's rendition of the *link* 
represented by the element that uses the address, not the address 
itself. This is a very important distinction that we often don't make 
because we've become trained (mostly by HTML) to equate the address with 
the link. But the address is just plumbing. The real thing is the 
abstract link established by the elements and attributes involved. To 
keep with the plumbing analogy: it doesn't matter whether you use copper 
or PVC or a bucket brigade (addressing) what's important is the 
relationship established:  the relationship between the tub and the 
water: how you got to the water is immaterial. But at the same time, you 
want the same result every time from a particular *type* of pipe--you 
don't want turning the tap in the tub to sometimes return fresh water 
and sometimes return sewage and sometimes return nothing. [The other 
implication is that you should be able to change the pipes without 
breaking the relationship: if I replace iron with PVC I should still get 
water to the tub.]

Addressing syntax and semantics is absolutely a syntax issue, not a 
processing issue, any more than the rules for parsing start tags and end 
tags is a processing issue.

If DITA wants to define a way to declare the addressing scheme you're 
using, that would be different, but DITA 1.x does not and therefore all 
valid DITA applications are obligated to use DITA's addressing syntax.

Whether or not a CMS assigns globally unique IDs to elements is 
irrelevant: the spec says elements are addressed by ID within the scope 
of their containing topic. If a CMS stores data with non-DITA addresses 
then it has an obligation to change them back to DITA addresses on 
demand, or it can't claim to be a DITA CMS.

In addition, in this particular case, there's no way to distinguish a 
bare element ID reference from a topic ID reference since topics and 
elements *could have the same ID* (because topic IDs and element IDs are 
distinct namespaces in DITA).

The address and the thing addressed (and what you do with it) are two 
entirely distinct domains of both semantics and processing. The only 
place in DITA where they are tightly bound (or can be seen to be tightly 
bound) is conref, where the processing effect of a conref is, 
notionally, applied before any other processing, such that it should be 
both consistently applied and effectively transparent to downstream 
processes (that is, renderers). Of course that doesn't preclude building 
things like "conref report generators" that produce renderings that 
expose the details of the conreffing done, but the result they report 
must be consistent with the "normal" result.

That is, the whole point of conref, as distinct from all other link 
semantics in DITA, is that it defines effective content structures 
independent of rendering applied, rather than establishing relationships 
that can usefully have different rendered expressions.

By contrast, xrefs may be rendered in an infinite number of ways, but 
the *thing referenced* by a given href value is invariant (or, with 
keyref, deterministic in the context of a given map).

In both cases, conref and xref, the addressing syntax and semantics are 
identical but the processing implications for the addressed result and 
the relationship established by the elements involved are very different.

> JO: See my comment below that starts out “I just think that if we make 
> everything overrideable …”.
> 
> JO: Allowing specializations to give new meanings to or ignore the 
> meanings of existing attribute/value pairs (scope=”external”).
> MP: maybe there's a difference here between "meaning" and "behavior". 
> For example, current behavior for scope="external" might be to open up a 
> new browser window - but in a particular delivery context they might 
> actually want to popup an intermediate window that says "you're leaving 
> the website and everything after this is unwarrantied" or something. Not 
> changing the meaning, but definitely changing the behavior.

I agree with MP here: the meaning of scope is fixed, the rendition 
effect is variable. In any case, we can think of things like scope= as 
falling into the zone of "hints" for which no hard and fast semantic or 
processing result can really be defined precisely because they cover 
cases where the boundary conditions are inherently fuzzy.

> JO: The specific example given here seems fine to me.  But take a 
> related example, that uses scope=”peer”. Today scope=”peer” is used to 
> say that the referenced item isn’t currently available for processing, 
> but it is part of the same document set.  I think this definition should 
> be true in all cases.  What one does with items that are part of the 
> “same document set” could be customized, but not the fact that the item 
> is considered part of the same document set.

I think this is a case of bad spec writing: "same document set" cannot 
be defined because we have no formal definition in DITA of "same", 
"document" (other than "XML document") or "document set". In that light 
it's just handwaving (and thus falls at least back to hint status).

But if the notion of "document set" was formally defined then authors 
and implementors would be able to tell with some confidence whether or 
not what they had was a "document set" and therefore both what "peer" 
means in their environment and whether or not its relevant.

For example, if by "document set" we mean "set of topics and maps 
managed in the same storage or management scope such that it is possible 
to get immediate knowledge of the properties of any topic in thet set" 
then we can see that peer can map into things like "all the topics my 
CVS working set or my Oxygen project or within my CMS or known to be 
available on these servers with this range of base URIs".

> JO: Allowing specializations to ignore @lockmeta.
> MP: I can imagine a draft review process that pulled in "author" info 
> from the target topics, even though lockmeta was set, because they 
> wanted to use a single map for both review and for final publication, 
> and they only wanted the author info for review... So in this case, I am 
> imagining a process that would ignore lockmeta to do a particular 
> metadata fetch based on business need rather than specialization.

> JO: Wouldn’t it be better to honor lockmeta and always push or not push 
> the metadata values from the map into the topic, and then using an 
> output appearance customization render or not render the “author” info 
> as appropriate for review or for final publication?
> 
> JO: Or wouldn’t it be better to define lockmeta as an attribute that can 
> inherit its value and then add lockmeta to the map root element, 
> topicref, topichead, and topicgroup so that someone that wants this 
> behavior can change the value for an entire document or portions of a 
> document as desired?
> 
> JO: Or to define a way to set, change, or delete attribute values using 
> conditional processing and ditaval?
> 
> JO: Allowing properties that normally cascade from a map to a topic to 
> not cascade depending on the specializations in use.
> MP: if a group was doing extensive customization in a map, and was 
> tracking authorship of the map at a chapter level, I can imagine 
> overriding the normal cascade of metadata from map to topic to stop 
> author from cascading and implying authorship of the actual topics 
> rather than of the referencing map sections.  Again, a customization not 
> based on specialization, but still definitely an override of default 
> behavior.

This may be a case where we need to distinguish between "actual" and 
"effective" values. That is, a processor should know both what the 
actual value of any given metadata value is as well as what the 
effective value is and give the option of reporting one or the other or 
both, as appropriate.

In query terms (which is where this will be important for me as a 
DITA-aware CMS implementor), I would like to be able to find both all 
topics whose effective author value is "MP" as well as all those topics 
whose actual author value is "MP". To determine the first value I have 
to take @lockmeta into account but to determine the second I have to 
ignore it.

Cheers,

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