OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [dita] Terminology issues: Linking and addressing terms?Referencing and referenced element?


Title: Re: [dita] Terminology issues: Linking and addressing terms? Referencing and referenced element?
I really think we need examples here — the definitions are too circular, which isn’t surprising considering the concept is circular. You need three elements to make a concept understandable: a definition, an example, and a non-example. We have the first part, but are missing the example and maybe the non-example.

I recommend an example — that would easily clarify the idea we’re trying to convey.
JoAnn


On 12/3/09 5:32 AM, "Kristen James Eberlein" <kris@eberleinconsulting.com> wrote:

Ouch. I think we have a problem here. I look at the two definitions and find them VERY difficult to mentally parse. If I have problems with them -- and I've been spending most of the last six months working on DITA full-time, then I think a lot of other people will also.

My analysis of the problem is:
  1. The two definitions are circular.
  2. We are trying to cram way too much information into a definition
Here's what I put in the terminology.dita topic yesterday morning as a temporary placeholder:

Referencing element
An element which specifies one of the following DITA attributes in order to address another DITA element:
Referenced element
An element that is referenced by another DITA element (the referencing element). The referencing element specifies one of the following DITA attributes:
The referenced element is the target of the DITA attribute.

Obviously I didn't have a complete list of the relevant attributes ...

Now I have to go and look up information about attributes that are unfamiliar to me (@mapref, @longdescref, @anchorref), and well as the <object> element :(

I do find "addressing attribute" to be a potentially useful and descriptive term for the particular groups of attributes. Some of these attributes fall into the "id-atts attribute group"; one of my review comments during the last review was to suggest that we use more descriptive names for the groups of attributes, rather than the names of the literal parameter entities that are used to organize the attribute declarations. We won't be doing this for DITA 1.2, but it's definitely something that we need to consider for DITA 1.3. See http://wiki.oasis-open.org/dita/LangRefAttributes if you want to follow the review thread.

Kris


Bruce Nevin (bnevin) wrote:

Then maybe this rev. 3 has got it:

Referencing element
An element that identifies a referenced element in the value of an addressing attribute. The addressing attributes include href, conref, conrefend, keyref, conkeyref, mapref, longdescref, and anchorref. See referenced element. This term may also be used for an <object> element insofar as its archive, classid, and data attributes are used to specify the data, resources, and implementation of a non-XML object.
 
Referenced element
The element that a referencing element identifies in the value of one of the addressing attributes. The addressing attributes include href, conref, conrefend, keyref, conkeyref, mapref, longdescref, and anchorref. See referencing element.

ø¤º°`°º¤ø,¸¸,ø¤º°`°º¤ø,¸¸,ø¤º°`°º¤ø

Does this hook us into making "addressing attribute" a defined term? I hope we can stop with defining it locally like this.

I don't know if we actually use source/target anywhere that we talk about <object> (we don't seem to in the lang ref), but someone might use referring/referenced in the future. I omitted @codebase since it only sets a base URL to which the other URLs are relative (when that base URL is other than that of the current document).

Question:
The "text description of the graphic or object" that @longdescref references--is that text contained in a DITA element? If not (or if not necessarily) it might call for an "also used" sentence like that for @archive, etc.


  
 

-----Original Message-----
From: Ogden, Jeff [mailto:jogden@ptc.com]
Sent: Wednesday, December 02, 2009 4:44 PM
To: Eliot Kimber; Bruce Nevin (bnevin); Kristen James Eberlein
Cc: dita
Subject: RE: [dita] Terminology issues: Linking and
addressing terms? Referencing and referenced element?

Bruce Nevin wrote:
    
 


one of the following attributes: href, conref, keyref,
        
 


conkeyref ...
    
 


[complete the list].
        
 


Eliot Kimber wrote:
    
 

Add conrefend and I think the list of addressing attributes is
      
 

complete.

These need to be on the list too:  @mapref, @longdescref, and
@anchorref

I'm less sure about:  @archive, @classid, @codebase, and
@data all on <object>

And without more research, I can't be sure that there aren't
a few more tucked away that I don't remember.  The above is
everything from a list I made and last updated in June 2007.

   -Jeff

    
 

-----Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com]
Sent: Wednesday, December 02, 2009 12:59 PM
To: Bruce Nevin (bnevin); Kristen James Eberlein
Cc: dita
Subject: Re: [dita] Terminology issues: Linking and
      
 

addressing terms?
    
 

Referencing and referenced element?

On 12/2/09 11:05 AM, "Bruce Nevin (bnevin)"
      
 

<bnevin@cisco.com> <mailto:bnevin@cisco.com>  wrote:
    
 


Here's a straw man for starters:

Referencing element
The element which identifies its referenced element in
        
 


the value of
    
 

one
      
 

of the following attributes: href, conref, keyref, conkeyref ...
[complete the list]. See referenced element.
        
 


Referenced element
The element which is identified in a referencing element by the
        
 


value
    
 

of
      
 

one of the following attributes: href, conref, keyref,
        
 


conkeyref ...
    
 


[complete the list]. See referencing element.

Whale away at it!
        
 

C/which/that/

Add conrefend and I think the list of addressing attributes is
      
 

complete.
    
 

Cheers,

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



      
 

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

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


    
 


---------------------------------------------------------------------
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




  

--------------------------------------------------------------------- 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


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]