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? Referencingand referenced element?


Hi Bruce,

Your proposed definitions aren't definitions in the sense one expects in a glossary or explanation of terms. Your definitions talk about the defined term, but the don't say what the defined term IS. One is left still wondering what these things are.

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

Inactive hide details for "Bruce Nevin (bnevin)" ---12/03/2009 01:07:24 PM---Kris wrote:  My analysis of the problem is:"Bruce Nevin (bnevin)" ---12/03/2009 01:07:24 PM---Kris wrote: My analysis of the problem is:


From:

"Bruce Nevin (bnevin)" <bnevin@cisco.com>

To:

"Ogden, Jeff" <jogden@ptc.com>, Kara Warburton/Toronto/IBM@IBMCA, "Joann Hackos" <joann.hackos@comtech-serv.com>

Cc:

"DITA TC" <dita@lists.oasis-open.org>, "Eliot Kimber" <ekimber@reallysi.com>, "Kristen James Eberlein" <kris@eberleinconsulting.com>

Date:

12/03/2009 01:07 PM

Subject:

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





Kris wrote: 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:jogden@ptc.com]
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:kara@ca.ibm.com]
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:

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:

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

Inactive hide details for Joann Hackos ---12/03/2009 08:47:07 AM---I really think we need examples here ― the definitions are 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 <joann.hackos@comtech-serv.com>

To:

Kristen James Eberlein <kris@eberleinconsulting.com>, "Bruce Nevin (bnevin)" <bnevin@cisco.com>

Cc:

"Ogden, Jeff" <jogden@ptc.com>, Eliot Kimber <ekimber@reallysi.com>, DITA TC <dita@lists.oasis-open.org>

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" <
kris@eberleinconsulting.com> wrote:

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