Re: [dita] Conref terminology: Referencing element and referencedelement

Bruce, thanks for the feedback. I'll keep it in
mind for the DITA 1.2 spec; the text that I posted to the list was for
an article for the DITA Adoption Technical Committee.

Kris

Bruce Nevin (bnevin) wrote:

  
  
  
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