Kris wrote:
My analysis of the problem
is:
The two definitions are circular.
We are trying to cram way too much
information into a definition
These two definitions are reciprocal because together
they define a relationship. I don't find that dizzying, but that may be because
(in linguistics) I'm used to thinking of relationships which are not easy to
TalkAboutAllAtOnceInOneExpression so we talk about one aspect at a time. When I
see a reciprocal definition I pop up a level to think about the relationship.
But that doesn't make it good clear writing practice for every
reader!
I agree with simplifying by putting the list of
attributes elsewhere. I said that the addressing attributes "include" those
listed as a hedge against incomplete recollection. Another tack would be to say
"the most important of the addressing attributes are ...".
Jeff, I dropped @codebase from the list because it
(optionally) supports the addressing attributes on <object>, but does not
itself address a referenced element. But under the last proposal above we could
drop the entire <object> set from the list.
I agree that we should not use "target" in any form.
Nominal and verbal uses are also equivocal over the two points of view --
the target of the link vs. the target of the content. We know we're talking
about a link addressing a "target" element but in some contexts readers think of
content being reused at a "target" element's location. (I don't think it's an
audience problem so much as a context problem. We have seen both senses in the
spec. and the ref.)
Going back to the first point, suppose we start each
definition by asserting the relationship explicitly. Maybe something like
this:
Referencing element
Content reuse requires a relationship between a referencing
element and a referenced element. An attribute on the referencing element is set
to the address of the referenced element.
Example:
...
See referenced element; addressing
attribute.
Referenced
element
Content reuse
requires a relationship between a referencing element and a referenced element.
The address of the referenced element is specified in the value of an attribute
on the referencing element.
Example:
...
See referencing
element; addressing attribute.
______________________________________________
I assume here that we omit the <object>
attributes from the list.
We don't have to say everything in each single definition.
Although DITA dogma says a glossary entry is a concept, definitions seldom stand
alone. I simplified "addressing attribute" to "attribute" because "see
addressing attribute" provides the necessary information if the reader wants
it.
/Bruce
From: Ogden, Jeff [mailto:]
Sent: Thursday, December 03, 2009 12:12 PM
To: Kara
Warburton; Joann Hackos
Cc: Bruce Nevin (bnevin); DITA TC; Eliot
Kimber; Kristen James Eberlein
Subject: RE: [dita] Terminology
issues: Linking and addressing terms? Referencing and referenced
element?
The
list of ※addressing§ attributes isn＊t complete. It might be better to
skip the list of addressing attributes and just make the definition something
like this:
An element that
targets another DITA element by using an addressing attribute such as @href,
@conref, @keyref, and @conkeyref.
More
important than the definitions is using the terminology correctly elsewhere in
the DITA spec. and avoiding the terms source and target.
But
if we feel compelled to include a list of all of the ※addressing§ attributes,
then as mentioned in previous e-mails, the list needs to include at
least:
@href, @conref,
@keyref, @conkeyref
@conrefend
@mapref,
@longdescref, and @anchorref
and
possibly @archive,
@classid, @codebase, and @data (all on <object>)
-Jeff
From: Kara Warburton
[mailto:]
Sent: Thursday, December 03, 2009 9:47
AM
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
From:
Joann Hackos
<>
To:
Kristen James Eberlein
<>, "Bruce Nevin (bnevin)"
<>
Cc:
"Ogden, Jeff" <>, Eliot
Kimber <>, DITA TC
<>
Date:
12/03/2009 08:47 AM
Subject:
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"
<> 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:]
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:]
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)"
<> <mailto:> 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
