RE: [dita] Conref terminology: Referencing element and referenced element

This
makes sense to me and is miles better than “source” and “target” (or was that “target”
and “source”?).

However
I’m so close to this subject that I’m not a good usabilty tester for it, so please
discount my vote.

 

Cheers,

Su-Laine

 

 

Su-Laine Yeo

Interaction
Design Specialist 

JustSystems
Canada, Inc.

Office:
778-327-6356 



www.justsystems.com 

 

 

From: Bruce Nevin (bnevin)
[mailto:] 

Sent: Thursday, October 08, 2009 7:08 PM

To: Kristen James Eberlein; Park Seth-R01164

Cc: DITA TC

Subject: RE: [dita] Conref terminology: Referencing element and
referenced element

 

This is much clearer but still seems needlessly complicated by
combining the two sorts of information in one paragraph.

 

The terminological information must be given in its most general
form elsewhere for all types of linking. Is a link or allusion to that general
description appropriate? (I hesitate to say a "reference" to it ;-)

 

How's this?

 

The  referencing element is the element with the referencing
attribute (in this case, @conref) and the referenced element is the element
that is addressed by that attribute. See [topic name].

 

The element with the content to be pushed depends upon the type of
push operation. In the case of a push and replace operation, the content that
is pushed is contained in the referencing element. In the case of a push before
or push after operation, the referencing element uses a mark operation to
specify the location to which the content is pushed, and the content to be
pushed is in a second element which specifies the push operation. The reason
for this is to ensure that inserting a second such element at that
location is valid.

 

_______________________________

 

Note that the lang ref topic "The conref attribute" needs
updating (unless my copy is stale):

 

The conref attribute

This attribute is used to reference an ID on content that can be reused. It
allows reuse of DITA components from phrases to topics as well as maps and
pieces of maps.

Full details on how to resolve the conref attribute can be found in the DITA
Architectural specification. This topic primarily includes information on the
actual syntax required when using the conref attribute.

Typo (extraneous "a") in the arch spec topic
"Content reference":

 

A content reference can be a from one element to one other
element or from one element to a set of elements. 

 

 

From: Kristen James Eberlein
[mailto:] 

Sent: Thursday, October 08, 2009 2:30 PM

To: Park Seth-R01164

Cc: DITA TC

Subject: Re: [dita] Conref terminology: Referencing element and referenced
element

OK, here's
what I have drafted for my conref push article:

"All the rules and restrictions are designed to ensure that the result of
the push operation is valid DITA. This section uses the following terminology: 

The referencing element is
the element with the @conref attribute. In the case of a push and replace
operation, this element contains the content that is pushed. In the case of a
push before or a push after operation, this element specifies the location
where content is pushed; a second element contains the content that is pushed. 

The referenced element is the
element addressed by the @conref attribute; it is the element that is replaced,
prefaced, or followed by the content that is pushed."

Any
comments welcome.

Kris

Park Seth-R01164 wrote: 

I think the resolution was that the TC requests that the author
group consider making the terminology unambiguous. 

 

The proposed terminology (paraphrased):

 
The element with the referencing attribute (href, conref,
     keyref, etc.) is always the referencing element, regardless of the
     behavior of the reference. 

 
The referenced element is the element specified in the
     referencing attribute (or the resolved target of an indirect reference)
     of the referencing element.

This does not make it easier to explain conactions, but the
best we can do is make sure the terminology is unambiguous. For example:

 
When using conref pull (no conaction specified), the
     referenced element replaces the referencing element.

 
When using conref push, the referencing element replaces the
     referenced element.

 

(BTW, Don said specifically that he was sensitive to making
resolutions that impact arch spec activities.)

 

-sp

 

 

--------------------------------------------

seth
park

information
architect

Freescale
Semiconductor, Inc.



512.895.2463

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates
this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php