This whole conversation started because the referencing element (as
opposed to the referenced element) might be the target as is the case in conref
pull, so we decided we had to stay away from the words target and source.
paul
From: Kara Warburton
[mailto:kara@ca.ibm.com]
Sent: Thursday, 2009 December 03 8:47
To: Joann Hackos
Cc: Bruce Nevin (bnevin); DITA TC; Eliot Kimber; Ogden, Jeff; Kristen
James Eberlein
Subject: Re: [dita] Terminology issues: Linking and addressing terms?
Referencing and referenced element?
A few suggestions if you are open to something cleaner and which adheres to
terminology best practices. Since the 2nd defintion proposed by Kristen already
contained the word "target", I tried this as the verb in the
definitions rather than "address" which I find ambiguous. The main
change is not to repeat what the referencing element does in the definition of
the referenced element. Also, please lower case the terms. There should also be
a cross reference in both entries.
I also would prefer to remove the list of attributes if they can be grouped
into a definition elsewhere as suggested by Kirsten. I've modelled that below
in the 2nd proposal but I don't know enough about these attributes to know if
it is correct.
First proposal - attributes listed in definition of referencing element
referencing element
An element that targets another DITA element by using one of the following
attributes:
- @ conkeyref
- @conref
- @href
- @keyref
See also referenced element.
referenced element
An element that is the target of another DITA element. See also referencing
element.
Second proposal - separating attributes to their own
entry
referencing element
An element that targets another DITA element by using an addressing attribute.
See also referenced element.
referenced element
An element that is the target of another DITA element. See also referencing
element.
addressing attribute
One of the following attributes, which are used by a referencing element to
target a referenced element:
- @ conkeyref
- @conref
- @href
- @keyref
Kara Warburton
IBM Terminology
Office: 905-413-2170
Mobile: 905-717-8014
IBM terminology: http://w3.ibm.com/standards/terminology
Education about IBM terminology: http://w3.tap.ibm.com/medialibrary/media_set_view?id=4981
Joann Hackos ---12/03/2009 08:47:07 AM---I really think
we need examples here ¡ª the definitions are too circular, which isn¡¯t
surprising cons
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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:
- @conkeyref
attribute
- @conref
attribute
- @href
attribute
- @keyref
attribute
Referenced
element
An element that is referenced by another DITA element (the referencing
element). The referencing element specifies one of the following DITA
attributes:
- @conkeyref
attribute
- @conref
attribute
- @href
attribute
- @keyref
attribute
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